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This manual is a general reference for a standard CP/M system. 
Features of Apple SoftCard III CP/M may differ slightly in features 
Or operation from the system described in this manual. Consult 


your SoftCard III Installation and Operation Manual for specific 
details. 
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Introduction to 
CP/M Features and Facilities 


Introduction 


CP/M is a monitor control program for microcomputer system 
development which uses IBM-compatible flexible disks for backup 
storage. Using a computer mainframe based upon Intel’s 8080 
microcomputer, CP/M provides a general environment for program 
construction, storage, and editing, along with assembly and program 
check-out facilities. An important feature of CP/M is that it can be 
easily altered to execute with any computer configuration which 
uses an Intel 8080 (or Zilog Z-80) Central Processing Unit, and has 
at least 16K bytes of main memory with up to four IBM-compatible 
diskette drives. Although the standard Digital Research version 
operates on a single-density Intel MDS 800, several different 
hardware manufacturers support their own input-output drivers for 
CP/M. 


The CP/M monitor provides rapid access to programs through a 
comprehensive file management package. The file subsystem 
supports a named file structure, allowing dynamic allocation of file 
space as well as sequential and random file access. Using this file 
system, a large number of distinct programs can be stored in both 
source and machine executable form. 


CP/M also supports a powerful context editor, Intel-compatible 
assembler, and debugger subsystem. Optional software includes a 
powerful Intel-compatible macro assembler, symbolic debugger, 
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along with various high-level languages. When coupled with CP/M’s 
Console Command Processor, the resulting facilities equal or excel 
similar large computer facilities. 


CP/M is logically divided into several distinct parts: 


BIOS Basic I/O System (hardware dependent) 
BDOS Basic Disk Operating System 

CCP Console Command Processor 

TPA Transient Program Area 


The BIOS provides the primitive operations necessary to access 
the diskette drives and to interface standard peripherals (teletype, 
CRT, Paper Tape Reader/Punch, and user-defined peripherals), and 
can be tailored by the user for any particular hardware environment 
by “patching” this portion of CP/M. 


The BDOS provides disk management by controlling one or more 
disk drives containing independent file directories. The BDOS 
implements disk allocation strategies which provide fully dynamic 
file construction while minimizing head movement across the disk 
during access. Any particular file may contain any number of 
records, not exceeding the size of any single disk. In a standard 
CP/M system, each disk can contain up to 64 distinct files. The 
BDOS has entry points which include the following primitive 
operations which can be programmatically accessed: 


SEARCH Look for a particular disk file by name. 


OPEN Open a file for further operations. 
CLOSE Close a file after processing. 
RENAME Change the name of a particular file. 
READ Read a record from a particular file. 
WRITE Write a record onto the disk. 
SELECT Select a particular disk drive for 


further operations. 
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The CCP provides symbolic interface between the user’s console 
and the remainder of the CP/M system. The CCP reads the console 
device and processes commands which include listing the file 
directory, printing the contents of files, and controlling the operation 
of transient programs, such as assemblers, editors, and debuggers. 
The standard commands which are available in the CCP are listed 
in a following section. 


The last segment of CP/M is the area called the Transient Program 
Area (TPA). The TPA holds programs which are loaded from the 
disk under command of the CCP. During program editing, for 
example, the TPA holds the CP/M text editor machine code and 
data areas. Similarly, programs created under CP/M can be checked 
out by loading and executing these programs in the TPA. 


It should be mentioned that any or all of the CP/M component 
subsystems can be “overlayed” by an executing program. That is, 
once a user’s program is loaded into the TPA, the CCP, BDOS, and 
BIOS areas can be used as the program’s data area. A ‘bootstrap’ 
loader is programmatically accessible whenever the BIOS portion 
is not overlayed; thus, the user program need only branch to the 
bootstrap loader at the end of execution, and the complete CP/M 
monitor is reloaded from disk. 


It should be reiterated that the CP/M operating system is partitioned 
into distinct modules, including the BIOS portion which defines the 
hardware environment in which CP/M is executing. Thus, the 
standard system can be easily modified to any non-standard 
environment by changing the peripheral drivers to handle the 
custom system. 
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An Overview of CP/M 2.0 Facilities 


CP/M 2.0 is a high-performance single-console operating system 
which uses table driven techniques to allow field configuration to 
match a wide variety of disk capacities. All of the fundamental file 
restrictions are removed, while maintaining upward compatibility 
from previous versions of release 1. Features of CP/M 2.0 include 
field specification of one to sixteen logical drives, each containing 
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up to eight megabytes. Any particular file can reach the full drive 
size with the capability to expand to thirty-two megabytes in future 
releases. The directory size can be field configured to contain any 
reasonable number of entries, and each file is optionally tagged 
with read/only and system attributes. Users of CP/M 2.0 are 
physically separated by user numbers, with facilities for file copy 
operations from one user area to another. Powerful relative-record 
random access functions are present in CP/M 2.0 which provide 
direct access to any of the 65536 records of an eight megabyte file. 


All disk-dependent portions of CP/M 2.0 are placed into a BIOS- 
resident “disk parameter block” which is either hand coded or 
produced automatically using the disk definition macro library 
provided with CP/M 2.0. The end user need only specify the 
maximum number of active disks, the starting and ending sector 
numbers, the data allocation size, the maximum extent of the 
logical disk, directory size information, and reserved track values. 
The macros use this information to generate the appropriate tables 
and table references for use during CP/M 2.0 operation. Deblocking 
information is also provided which aids in assembly or disassembly 
of sector sizes which are multiples of the fundamental 128 byte 
data unit, and the system alteration manual includes general-purpose 
subroutines which use this deblocking information to take advantage 
of larger sector sizes. Use of these subroutines, together with the 
table driven data access algorithms, make CP/M 2.0 truly a universal 
data management system. 


File expansion is achieved by providing up to 512 logical file 
extents, where each logical extent contains 16K bytes of data. 
CP/M 2.0 is structured, however, so that as much as 128K bytes of 
data is addressed by a single physical extent (corresponding to a 
single directory entry), thus maintaining compatibility with previous 
versions while taking full advantage of directory space. 


Random access facilities are present in CP/M 2.0 which allow 
immediate reference to any record of an eight megabyte file. Using 
CP/M’s unique data organization, data blocks are only allocated 
when actually required and movement to a record position requires 
little search time. Sequential file access is upwardly compatible 
from earlier versions to the full eight megabytes, while random 
access compatibility stops at 512K byte files. Due to CP/M 2.0's 
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simpler and faster random access, application programmers are 
encouraged to alter their programs to take full advantage of the 2.0 
facilities. 


Several CP/M 2.0 modules and utilities have improvements which 
correspond to the enhanced file system. STAT and PIP both account 
for file attributes and user areas, while the CCP provides a “login” 
function to change from one user area to another. The CCP also 
formats directory displays in a more convenient manner and 
accounts for both CRT and hard-copy devices in its enhanced line 
editing functions. 


Functional Description of CP/M 


The user interacts with CP/M primarily through the CCP, which 
reads and interprets commands entered through the console. In 
general, the CCP addresses one of several disks which are online 
(the standard system addresses up to four different disk drives). 
These disk drives are labelled A, B, C, and D. A disk is “logged in” if 
the CCP is currently addressing the disk. In order to clearly 
indicate which disk is the currently logged disk, the CCP always 
orompts the operator with the disk name followed by the symbol 
“>” indicating that the CCP is ready for another command. Upon 
initial start up, the CP/M system is brought in from disk A, and 
the CCP displays the message 


xxK CP/M VER m.m 


where xx is the memory size (in kilobytes) which this CP/M system 
manages, and m.m is the CP/M version number. Following system 
signon, CP/M automatically logs in disk A, prompts the user with 
the symbol “A>” (indicating that CP/M is currently addressing 

disk “A’), and waits for a command. The commands are implemented 
to two levels: built-in commands and transient commands. 
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7 General Command Structure 


re 


Built-in commands are a part of the CCP program itself, while 
transient commands are loaded into the TPA from disk and 
executed. The built-in commands are 


a 


J 


ERA Erase specified files. 

DIR Displays file names in the directory. 

REN Rename the specified file. 

SAVE Save memory contents in a file. 

TYPE Type the contents of a file on the logged disk. 

USER Move to another area within the same 
directory. 


Nearly all of the commands reference a particular file or group of 
files. The form of a file reference is specified below. 
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File References 


A file reference identifies a particular file or group of files on a 
particular disk attached to CP/M. These file references can be 
either “unambiguous” (ufn) or “ambiguous” (afn). An unambiguous 
file reference uniquely identifies a single file, while an ambiguous 
file reference may be satisfied by a number of different files. 


i im | 
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File references consist of two parts: the primary name and the 
secondary name. Although the secondary name is optional, it 
usually is generic; that is, the secondary name ‘ASM,’ for 
example, is used to denote that the file is an assembly language 
source file, while the primary name distinguishes each particular 
source file. The two names are separated by a “.” as shown below: 


PPPPPPPP.sss 


Where pppppppp represents the primary name of eight characters 
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or less, and sss is the secondary name of no more than three 
characters. As mentioned above, the name 


PPPPPPPP 


is also allowed and is equivalent to a secondary name consisting 
of three blanks. The characters used in specifying an unambiguous 
file reference cannot contain any of the special characters 

— ., sp Se TT 


while all alohanumerics and remaining special characters are 
allowed. 


An ambiguous file reference is used for directory search and 
pattern matching. The form of an ambiguous file reference is 
similar to an unambiguous reference, except the symbol *?” may 
be interspersed throughout the primary and secondary names. In 
various commands throughout CP/M, the “?” symbol matches any 
character of a file name in the “?” position. Thus, the ambiguous 
reference 


X?Z.C?M 

is satisfied by the unambiguous file names 
XYZ.COM 

and 
X3Z.CAM 

Note that the ambiguous reference 


is equivalent to the ambiguous file reference 


0 a at eal al at a ad al 
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while 
PPppppppp.* 
and 
* SSS 
are abbreviations for 
pppppppp.??? 
and 
2922222? SSS 
respectively. As an example, 
DIR *.* 


is interpreted by the CCP as a command to list the names of all disk 
files in the directory, while 


DIR X.Y 
searches only for a file by the name X.Y. Similarly, the command 
DIR X?Y.C?M 


causes a search for all (unambiguous) file names on the disk which 
satisfy this ambiguous reference. 


The following file names are valid unambiguous file references: 


X XYZ GAMMA 
KY XYZ.COM GAMMA.1 
As an added convenience, the programmer can generally specify 


the disk drive name along with the file name. In this case, the drive 
name is given as a letter A through Z followed by a colon (:). The 
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specified drive is then “logged in” before the file operation occurs. 
Thus, the following are valid file names with disk name prefixes: 


A:X.Y BoXYZ C:GAMMA 
Z:XYZ.COM  B:X.A?M C:*ASM 
It should also be noted that all alphabetic lower case letters in file 


and drive names are always translated to upper case when they 
are processed by the CCP. 


Switching Disks 


The operator can switch the currently logged disk by typing the 
disk drive name (A, B, C, or D) followed by a colon (:) when the CCP 
is waiting for console input. Thus, the sequence of prompts and 
commands shown below might occur after the CP/M system is 
loaded from disk A: 

16K CP/M VER 1.4 

A>DIR List all files on disk A. 

SAMPLE ASM 

SAMPLE PRN 

A>B: Switch to disk B. 

B>Dir*.ASM List all “ASM” files on B. 

DUMP ASM 

FILES ASM 

B>A: Switch back to A. 


Form of Built-in Commands 


The file and device reference forms described above can now be 
used to fully specify the structure of the built-in commands. In the 
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description below, assume the following abbreviations: 


ufn unambiguous file reference 
afn ambiguous file reference 
cr carriage return 


Further, recall that the CCP always translates lower case characters 
to upper case characters internally. Thus, lower case alphabetics 
are treated as if they are upper case in command names and file 
references. 


ERAse Command 
ERA afn 


The ERA (erase) command removes files from the currently 
logged-in disk (i.e., the disk name currently prompted by CP/M 
preceding the “>’). The files which are erased are those which 
satisfy the ambiguous file reference afn. The following examples 
illustrate the use of ERA: 


ERA X.Y The file named X.Y on the currently 
logged disk is removed from the disk 
directory, and the space is returned. 


ERA X.* All files with primary name X are 
removed from the current disk. 
ERA *.ASM All files with secondary name ASM 


are removed from the current disk. 


ERA X?Y.C?M All files on the current disk which 
satisfy the ambiguous reference 
X?Y.C?M are deleted. 


ERA *.* Erase all files in the current user's 
directory. (See USER, page 15.) The 
CCP prompts with the message 


ALL (Y/N)? 


which requires a Y response before 
files are actually removed. 
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ERA B:*.PRN All files on drive B which satisfy 
the ambiguous reference 


are deleted, independently of the 
currently logged disk. 


DIRectory Command 
DIR afn 


The DIR(directory) command causes the names of all files which 
satisfy the ambiguous file name afn to be listed at the console 
device. As a special case, the command 


DIR 


lists the files on the currently logged disk (the command “DIR” is 
equivalent to the command “DIR *.*”’). Valid DIR commands are 
shown below. 

DIR X.Y 

DIR X?Z.C?M 

DIR ?7.Y 
Similar to other CCP commands, the afn can be preceded by a 
drive name. The following DIR commands cause the selected 
drive to be addressed before the directory search takes place. 

DIR B: 

DIR B:X.Y 

DIR B:*.A?M 
If no files can be found on the selected diskette which satisfy the 


directory request, then the message “NOT FOUND’ is typed at 
the console. 
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REName Command 
REN ufn2 = ufn1 


The REN (rename) command allows the user to change the 
names of files on disk. The file satisfying ufn2 is changed to ufn1. 
The currently logged disk.is assumed to contain the file to 

rename (ufn1). The CCP also allows the user to type a left-directed 
arrow instead of the equal sign, if the user’s console supports the 
graphic character. Examples of the REN command are 


REN X.Y =Q.R The file Q.R is changed 
to X.Y. 

REN XYZ.COM = XYZ.XXX The file XYZ.XXX is 
changed to XYZ.COM. 


The operator can precede either ufn1 or ufn2 (or both) by an 
optional drive address. Given that ufn1 is preceded by a drive 
name, then ufn2 is assumed to exist on the same drive as ufn1. 
Similarly, if ufn2 is preceded by a drive name, then ufn1 is assumed 
to reside on that drive as well. If both ufni and ufn2 are preceded 
by drive names, then the same drive must be specified in both 
cases. The following REN commands illustrate this format. 


REN A:X.ASM = Y.ASM The file Y.ASM is 
changed to X.ASM on 
drive A. 


REN B:ZAP.BAS = ZOT.BAS The file ZOT.BAS Is 
changed to ZAP.BAS on 
drive B. 


REN B:A.ASM = B:A.BAK The file A.BAK is 
renamed to A.ASM on 
drive B. 


If the file ufn1 is already present, the REN command will respond 
with the error “FILE EXISTS” and not perform the change. If 
ufn2 does not exist on the specified diskette, then the message 
“NOT FOUND?’ is printed at the console. 
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SAVE Command 
SAVE nufn 


The SAVE command places n pages (256-byte blocks) onto disk 
from the TPA and names this file ufn. In the CP/M distribution 
system, the TPA starts at 100H (hexadecimal), which is the 
second page of memory. Thus, if the user’s program occupies the 
area from 100H through 2FFH, the SAVE command must specify 
two pages of memory. The machine code file can be subsequently 
loaded and executed. Examples are: 


SAVE 3 X.COM Copies 100H through 
3FFH to X.COM. 
SAVE 40 Q Copies 100H through 


28FFH to Q (note that 

28 is the page count In 
28FFH, and that 28H = 
2*16+8 = 40 decimal). 


SAVE 4 X.Y Copies 100H through 
4FFH to X.Y. 


The SAVE command can also specify a disk drive in the afn portion 
of the command, as shown below. 


SAVE 10 B:ZOT.COM Copies 10 pages (100H 
through OAFFH) to the 
file ZOT.COM on drive B. 


The SAVE operation can be used any number of times without 
altering the memory image. 


TYPE Command 
TYPE ufn 


The TYPE command displays the contents of the ASCII source file 
ufn on the currently logged disk at the console device. Valid 
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TYPE commands are 


TYPE X.Y 
TYPE X.PLM 
TYPE XXX 
The TYPE command expands the tabs (ctl-| characters), assuming 


tab positions are set at every eighth column. The ufn can also 
reference a drive name as shown below. 


TYPE B:X.PRN The file X.PRN from 
drive B is displayed. 
USER Command 
USER n 


Where n is an integer value in the range O to 15. 


Upon cold start, the operator is automatically “logged” into user 
area number O. The operator may issue the USER command at any 
time to move to another logical area within the same directory. 


Drives which are logged in while addressing one user number 
are automatically active when the operator moves to another user 
number since a user number is simply a prefix which accesses 
particular directory entries on the active disks. 


The active user number is maintained until changed by a subsequent 


USER command, or until a cold start operation when user O is 
again assumed. 


Line Editing and Output Control 


The CCP allows certain line editing functions while typing command 
lines. “Control” indicates that the Control key and the indicated key 
are to be pressed simultaneously. CCP commands can generally be 
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up to 255 characters in length; they are not acted upon until the 
carriage return key is pressed. 


rubout/delete 
Control C 
Control E 


Control H 


Control J 
Control M 
Control R 


Control X 


Remove and echo last character typed. 


Reboot CP/M when at beginning of line. 


Physical end of line: carriage Is 
returned, but line is not sent until the 
carriage return key is depressed. 


Backspace one character position. 
Produces the backspace overwrite 
function. Can be changed internally 
to another character, such as delete, 
through a simple single byte change. 


Line feed. Terminates current input. 
Carriage return. Terminates input. 


Retype current command line after 
new line. 


Backspace to beginning of current line. 


The line editor keeps track of the current prompt column position 
so that the operator can properly align data input following a 
Control R or Control X command. 


The control functions Control P and Control S affect console output 


as shown below. 


Control P 


Control S 


Copy all subsequent console output 

to the currently assigned list device 
(see the STAT command). Output is sent 
to both the list device and the console 
device until the next Control P is typed. 


Stop the console output temporarily. 
Program execution and output continue 
when the next character Is typed at 

the console (e.g., another Control S). 
This feature is used to stop output on 
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high speed consoles, such as CRT’s, 
in order to view a segment of output 
before continuing. 


Transient Commands 


Transient commands are loaded from the currently logged disk and 
executed in the TPA. The transient commands defined for execution 
under the CCP are shown below. Additional functions can easily be 
defined by the user (see the LOAD command definition). 


STAT 


ASM 


LOAD 


DDT 


PIP 


ED 


SUBMIT 


DUMP 


List the number of bytes of storage 
remaining on the currently logged disk, 
provide statistical information about 
particular files, and display or alter 
device assignment. 


Load the CP/M assembler and 
assemble the specified program from 
disk. 


Load the file in Intel “hex” machine 
code format and produce a file in 
machine executable form which can be 
loaded into the TPA (this loaded 
program becomes a new command 
under the CCP). 


Load the CP/M debugger into TPA 
and start execution. 


Load the Peripheral Interchange 
Program for subsequent disk file and 
peripheral transfer operations. 


Load and execute the CP/M text 
editor program. 


Submit a file of commands for 
batch processing. 


Dump the contents of a file in hex. 
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Transient commands are specified in the same manner as built-in 
commands, and additional commands can be easily defined by the 
user. As an added convenience, the transient command can be 


preceded by a drive name, which causes the transient to be loaded 


from the specified drive into the TPA for execution. Thus, the 
command 


B:STAT 


causes CP/M to temporarily “log in’ drive B for the source of the 
STAT transient, and then return to the original logged disk for 
subsequent processing. 


The basic transient commands are listed in detail below. 


STAT 


The STAT command provides general statistical information about 
file storage and device assignment. It is initiated by typing one of 
the following forms: 


STAT 
STAT “command line” 


Special forms of the “command line” allow the current device 
assignment to be examined and altered as well. The various 
command lines which can be specified are shown below, with an 
explanation of each form shown to the right. 


STAT <cr> If the user types an empty command 
line, the STAT transient calculates the 
storage remaining on all active drives, 
and prints a message 


x: R/W, SPACE: nnnk 
or 
x: R/O, SPACE: nnnk 


for each active drive x, where R/W 
indicates the drive may be read or 
written, and R/O indicates the drive 
is read only (a drive becomes R/O by 
explicitly setting it to read only, as 
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STAT x: <cr 


STAT afn <cr> 


STAT x:afn <cr> 
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shown below, or by inadvertently changing 
diskettes without performing a warm 
start). The space remaining on the 
diskette in drive x is given in kilobytes 

by nnn. 


If a drive name is given, then the drive 

is selected before the storage is 
computed. Thus, the command “STAT B:” 
could be issued while logged into drive 
A, resulting in the message 


BYTES REMAINING ON B: nnnK 


The command line can also specify a set 
of files to be scanned by STAT. The files 
which satisfy afn are listed in alphabetical 
order, with storage requirements for each 
file under the heading 


RECS BYTS EX D:FILENAME.TYP 
rrrr bbbK ee d:pppppppp.sss 


where rrrr is the number of 128-byte 
records allocated to the file, bbb is the 
number of kilobytes allocated to the file 
(bbb=rrrr*128/1024), ee is the number of 
16K extensions (ee=bbb/16), d is the 
drive name containing the file (A...Z), 
pppppppp is the (up to) eight-character 
primary file name, and sss Is the 

(up to) three-character secondary name. 
After listing the individual files, the 
storage usage is Summarized. 


As aconvenience, the drive name can 

be given ahead of the afn. In this case, 
the specified drive is first selected, and 
the form “STAT afn’ is executed. 
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STAT d:filename.typ $S<cr> 
(‘““d:” is optional drive Produces the output display format: 
name and 


“filename.typ’ Is Size Recs Bytes Ext Acc 

stair eg or 48 48 6K 1 R/OA-ED.COM 
g 55 55 12K 1. R/O(A:PIPRCOM) 

name) 65536 128 2K 2 R/WA:X.DAT 


The $S parameter causes the “Size” 
field to be displayed. (The command 
may be used without the $S if desired.) 
The Size field lists the virtual file size 

in records, while the “Recs’ field sums 
the number of virtual records in each 
extent. For files constructed sequentially, 
the Size and Recs fields are identical. 
The “Bytes” field lists the actual number 
of bytes allocated to the corresponding 
file. The minimum allocation unit is 
determined at configuration time, and 
thus the number of bytes corresponds to 
the record count plus the remaining 
unused space in the last allocated 

block for sequential files. Random access 
files are given data areas only when 
written, so the Bytes field contains the 
only accurate allocation figure. In the 
case of random access, the Size field 
gives the logical end-of-file record 
position and the Recs field counts the 
logical records of each extent (each of 
these extents, however, may contain 
unallocated “holes” even though they 
are added into the record count). The 
“Ext” field counts the number of local 
16K extents allocated to the file. The 
‘Acc’ field gives the R/O or R/W access 
mode, which is changed using the 
commands shown below. The parentheses 
shown around the PIP-COM file name 
indicate that it has the “system” 
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indicator set, so that it will not be. 
listed in DIR commands. 


STAT d:filename.typ $R/O <cr> 


Places the file or set of files ina 

read-only status until changed by a 
subsequent STAT command. The R/O 
status is recorded in the directory with the 
file so that it remains R/O through 
intervening cold start operations. When a 
file is marked R/O, attempts to erase or 
write into the file result in a terminal BDOS 
message: Bdos Err on D: File R/O. 


STAT d:filename.typ $R/W <cr> 


Places the file in a permanent 
read/write status. 


STAT d:filename.typ $SYS <cr> 


Attaches the system indicator to the file. 


STATd:filename.typ $DIR <cr> 


STAT d:DSK: <cr> 


Removes the system indicator from the file. 


Lists the drive characteristics of the disk 
named by “d:’ which is in the range 

A:, B:, ..., P:. The drive characteristics 
are listed in the format: 


d: Drive Characteristics 
65536: 128 Byte Record Capacity 
8192: Kilobyte Drive Capacity 
128: 32 Byte Directory Entries 
O: Checked Directory Entries 
1024: Records/Extent 
128: Records/Block 
58: Sectors/Track 
2: Reserved Tracks 


The total record capacity is listed, followed 
by the total drive capacity listed in Kbytes. 
The number of checked entries is usually 
identical to the directory size for removable 
media, since this mechanism Is used to 
detect changed media during CP/M 
operation without an intervening warm 
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STAI DSK: <cr=> 


STAT USR: <er— 


start. The number of records per extent 
determines the addressing capacity of 
each directory entry (1024 times 128 bytes, 
or 128K in the example above). The 
number of records per block shows the 
basic allocation size (in the example, 128 
records/block times 128 bytes per record, 
or 16K bytes per block). The listing is then 
followed by the number of physical sectors 
per track and the number of reserved 
tracks. 


Lists drive characteristics as above for all 
currently active drives. 


Produces a list of the user numbers which 
have files on the currently addressed disk. 
The display format Is: 


Active User: O 
Active Files:013 


where the first line lists the currently 
addressed user number, as set by the last 
CCP USER command, followed by a list of 
user numbers scanned from the current 
directory. In the above case, the active 
user number is O (default at cold start), 
with three user numbers which have active 
files on the current disk. The operator can 
subsequently examine the directories of 
the other user numbers by logging in with 
USER 1, USER 2, or USER 3 commands, 
followed by a DIR command at the CCP 
level. 


The STAT command also allows control over the physical to logical 
device assignment (see the IOBYTE function described in the 
“CP/M Interface Guide’). In general, there are four logical peripheral 
devices which are, at any particular instant, each assigned to one of 
several physical peripneral devices. The four logical devices are 


named: 


CON: 


The system console device (used by CCP 
for communication with the operator) 
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RDR: The paper tape reader device 
PUN: The paper tape punch device 
Lor: The output list device 


The actual devices attached to any particular computer system are 
driven by subroutines in the BIOS portion of CP/M. Thus, the 
logical RDR: device, for example, could actually be a high speed 
reader, Teletype reader, or cassette tape. In order to allow some 
flexibility in device naming and assignment, several physical devices 
are defined, as shown below: 


TY: Teletype device (slow speed console) 
CRT: Cathode ray tube device 
(high speed console) 
BAT: Batch processing (console is current 
RDR:, output goes to current LST: device) 
UC1: User-defined console 
PTR; Paper tape reader (high speed reader) 
UR1: User-defined reader #1 
UR2: User-defined reader #2 
PTP: Paper tape punch (high speed punch) 
UP. User-defined punch #1 
UP2: User-defined punch #2 
LPT: Line printer 
UL: User-defined list device #1 


It must be emphasized that the physical device names may or may 

not actually correspond to devices which the names imply. That is, 

the PTP: device may be implemented as a cassette write operation, 
if the user wishes. The exact correspondence and driving subroutine 
is defined in the BIOS portion of CP/M. 
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The command: 
STAT VAL: <cr> 


produces a summary of the available status commands, resulting in 
the output: 


Temp R/O Disk: ad: =AR/O 


Set Indicator: d:filename.typ $R/O $R/W $SYS $DIR 
Disk Status: DSK: d:DSK: 

User Status: USR: 

lobyte Assign: 

GON. = TITY: CRT: BAT: UCT: 

RDR: =TTY: PTR: UR1: UR2: 

PUN: =TTY: PTP: UP1: UP2: 

LSi: =TTy¥: CRT: LPT: LT: 


In each case, the logical device shown to the left can take any of 
the four physical assignments shown to the right on each line. The 
current logical to physical mapping is displayed by typing the 
command 


SIA DEV: <cr> 
which produces a listing of each logical device to the left, and the 


current corresponding physical device to the right. For example, 
the list might appear as follows: 


CON: = CRT: 
RDR: = UR1: 
PUN: = PTP: 
LST: = TTY: 


The current logical to physical device assignment can be changed by 
typing a STAT command of the form 


STAT Id1 = pd1, Ild2 = pd2., ... , ldn = pdn <cr> 


where Id1 through Idn are logical device names, and pd1 through 
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pdn are compatible physical device names (i.e., Idi and pdi appear on 
the same line in the “VAL:” command shown above). The 

following are valid STAT commands which change the current logical 
to physical device assignments: 


STAT CON: = CRT: <cr> 
STAT PUN: = TTY:,LST: = LPT; RDR: =TTY: <cr 


ASM ufn 


The ASM command loads and executes the CP/M 8080 assembler. 
The ufn specifies a source file containing assembly language 
statements where the secondary name is assumed to be ASM, and 
thus is not specified. The following ASM commands are valid: 


ASM X 
ASM GAMMA 


The two-pass assembler is automatically executed. If assembly 
errors occur during the second pass, the errors are printed at the 
console. 


The assembler produces a file 
x.PRN 


where x is the primary name specified in the ASM command. The 
PRN file contains a listing of the source program (with imbedded 
tab characters if present in the source program), along with the 
machine code generated for each statement and diagnostic error 
messages, if any. The PRN file can be listed at the console using 
the TYPE command, or sent to a peripheral device using PIP 

(see the PIP command structure below). Note also that the PRN file 
contains the original source program, augmented by 
miscellaneous assembly information in the leftmost 16 columns 
(program addresses and hexadecimal machine code, for example). 
Thus, the PRN file can serve as a backup for the original source 
file: if the source file is accidentally removed or destroyed, the 
PRN file can be edited (see the ED operator's guide) by removing 
the leftmost 16 characters of each line (this can be done by issuing 
a single editor “macro” command). The resulting file is identical 

to the original source file and can be renamed (REN) from PRN to 
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ASM for subsequent editing and assembly. The file 
x HEX 


is also produced which contains 8080 machine language in Intel 
“hex” format suitable for subsequent loading and execution (see 
the LOAD commanda). For complete details of CP/M’s assembly 
language program, see the “CP/M Assembler Language (ASM) 
User’s Guide.’ 


Similar to other transient commands, the source file for assembly 
can be taken from an alternate disk by prefixing the assembly 
language file name by a disk drive name. Thus, the command 


ASM B:ALPHA <cr> 


loads the assembler from the currently logged drive and operates 
upon the source program ALPHA.ASM on drive B. The HEX and 
PRN files are also placed on drive B in this case. 


LOAD ufn cr 


The LOAD command reads the file ufn, which is assumed to 
contain “hex” format machine code, and produces a memory 
image file which can be subsequently executed. The file name ufn 
is assumed to be of the form 


x. HEX 


and thus only the name x need be specified in the command. 
The LOAD command creates a file named 


x.COM 


which marks it as containing machine executable code. The file is 
actually loaded into memory and executed when the user types 
the file name x immediately after the prompting character >" 
printed by the CCP. 


In general, the CCP reads the name x following the prompting 
character and looks for a built-in function name. If no function 
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name is found, the CCP searches the system disk directory for a 
-| file by the name 


J 


x.COM 


If found, the machine code is loaded into the TPA, and the 
program executes. Thus, the user need only LOAD a hex file once: 
it can be subsequently executed any number of times by simply 
typing the primary name. In this way, the user can “invent” new 
commands in the CCP. (Initialized disks contain the transient 
commands as COM files, which can be deleted at the user’s 
option.) The operation can take place on an alternate drive if the 
file name is prefixed by a drive name. Thus 


LOAD B:BETA 


brings the LOAD program into the TPA from the currently logged 
disk and operates upon drive B after execution begins. 


It must be noted that the BETA.HEX file must contain valid Intel 
format hexadecimal machine code records (as produced by the 
ASM program, for example) which begin at 100H, the beginning 
of the TPA. Further, the addresses in the hex records must be in 
ascending order; gaps in unfilled memory regions are filled with 
zeroes by the LOAD command as the hex records are read. Thus, 
LOAD must be used only for creating CP/M standard ‘COM’ files 
which operate in the TPA. Programs which occupy regions of 
memory other than the TPA can be loaded under DDT. 


PIP 


PIP is the CP/M Peripheral Interchange Program which implements 
the basic media conversion operations necessary to load, print, 
punch, copy, and combine disk files. The PIP program is initiated by 
typing one of the following forms 


PIP <cr> 
PIP “command line’ <cr> 


In both cases, PIP is loaded into the TPA and executed. In case 1, 
PIP reads command lines directly from the console, prompted 

with the “*” character, until an empty command line is typed (i.e., a 
single carriage return is issued by the operator). Each successive 
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command line causes some media conversion to take place 
according to the rules shown below. Form 2 of the PIP command 

is equivalent to the first, except that the single command line given 
with the PIP command is automatically executed, and PIP 
terminates immediately with no further prompting of the console 
for input command lines. The form of each command line is 


destination = source #1, source #2, ..., source #n <cr> 


where “destination is the file or peripheral device to receive the 
data, and “source #1, ..., source #n” represents a series of one or 
more files or devices which are copied from left to right to the 


destination. 


When multiple files are given in the command line (i.e., n>1), the 
individual files are assumed to contain ASCII characters, with an 
assumed CP/M ena-of-file character (ctl-Z) at the end of each file 
(see the O parameter to override this assumption). The equal 
symbol (=) can be replaced by a left-oriented arrow, if your console 
supports this ASCII character, to improve readability. Lower case 
ASCII alphabetics are internally translated to upper case to be 
consistent with CP/M file and device name conventions. Finally, 
the total command line length cannot exceed 255 characters (ctl-E 
can be used to force a physical carriage return for lines which 


exceed the console width). 


The destination and source elements can be unambiguous 
references to CP/M source files, with or without a preceding disk 
drive name. That is, any file can be referenced with a preceding 
drive name (A:, B:, C:, or D:) which defines the particular drive 
where the file may be obtained or stored. When the drive name 
is not included, the currently logged disk is assumed. Further, the 
destination file can also appear as one or more of the source 
files, in which case the source file is not altered until the entire 
concatenation is complete. If the destination file already exists, it 
is removed if the command line is properly formed (it is not 
removed if an error condition arises). The following command 
lines (with explanations to the right) are valid as input to PIP: 


X= Y <cr> 


Copy to file X from file Y, where 
X and Y are unambiguous file 
names; Y remains unchanged. 
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A= YZ =cr Concatenate files Y and Z and 
copy to file X, with Y and 
Z unchanged. 


X.ASM = Y.ASM,Z.ASM,FIN.ASM <cr> 
Create the file X.ASM from the 
concatenation of the Y, Z, and 
FIN files with type ASM. 


NEW.ZOT = B:OLD.ZAP <cr> Move acopy of OLD.ZAP from 
drive B to the currently logged 
disk; name the file NEW.ZOT. 


B:A.U. = B:B.V,A:C.W,D.X <cr> Concatenate file B.V from drive 
B with C.W from drive A and 
D.X. from the logged disk; 
create the file A.U on 
drive B. 


For more convenient use, PIP allows abbreviated commands for 
transferring files between disk drives. The abbreviated forms are 


PIP x: = afn <cr> 
PIP x: = y:afn <cr> 
PIP ufn = y: <cr> 
PIP x:ufn = y: <cr> 


The first form copies all files from the currently logged disk 
which satisfy the afn to the same file names on drive x (x =A...Z). 
The second form is equivalent to the first, where the source for 
the copy Is drive y (y =A...Z). The third form is equivalent to the 
command “PIP ufn = y:ufn <cr>” which copies the file given by 
ufn from drive y to the file ufn on drive x. The fourth form is 
equivalent to the third, where the source disk is explicitly given 
by y. 


Note that the source and destination disks must be different in 
all of these cases. If an afn is specified, PIP lists each ufn which 
satisfies the afn as it is being copied. If a file exists by the same 
name as the destination file, it is removed upon successful 
completion of the copy, and replaced by the copied file. 
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The following PIP commands give examples of valid disk-to-disk 
copy operations: 


B: = *.COM <cr> Copy all files which have the 
secondary name ‘COM’ to drive 
B from the current drive. 


fe = E:ZAP”* <cr Copy all files which have the 
primary name “ZAP” to drive 
A from drive B. 


ZAP.ASM = B: <cr> Equivalent to 

ZAP.ASM = B:ZAPASM 
B:ZOT.COM = A: <cr> Equivalent to 

B:ZOT.COM = A:ZOT.COM 
B: = GAMMA.BAS <cr> Same as 

B:GAMMA.BAS = GAMMA.BAS 
B: = A:GAMMA.BAS <cr> Same as 


B:GAMMA.BAS = A:GAMMA.BAS 

PIP also allows reference to physical and logical devices which are 
attached to the CP/M system. The device names are the same as 
given under the STAT command, along with a number of specially 

named devices. The logical devices given in the STAT command are 

CON: (console), RDR: (reader), PUN: (punch), and LST: (list) 


while the physical devices are 


TTY: (console, reader, punch, or list) 


CRT: (console, or list), UC1: (console) 
PTR: (reader), UR1: (reader), UR2: (reader) 
PTP: (punch), UP1: (punch), UP2: (punch) 
LPT: (list), UL1: (list) 


(Note that the “BAT:” physical device Is not included, since this 
assignment is used only to indicate that the RDR: and LST: devices 
are to be used for console input/output.) 


The RDR, LST, PUN, and CON devices are all defined within the 
BIOS portion of CP/M. (The current physical device mapping is 
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defined by IOBYTE; see the “CP/M Interface Guide’ for a 
discussion of this function.). The destination device must be capable 
of receiving data (i.e., data cannot be sent to the punch), and the 
source devices must be capable of generating data (i.e., the LST: 
device cannot be read). 


The additional device names which can be used in PIP commands 
are 


NUL: Send 40 “nulls” (ASCII 0’s) to the device (this 
can be issued at the end of punched output). 


EOF: Send a CP/M end-of-file (ASCII ctl-Z) to the 
destination device (sent automatically at the end 
of all ASCII data transfers through PIP). 


INP: Special PIP input source which can be “patched” 
into the PIP program itself: PIP gets the input data 
character-by-character by CALLing location 
103H, with data returned in location 109H (parity 
bit must be zero). 


OUT: Special PIP output destination which can be 
patched into the PIP program: PIP CALLs location 
106H with data in register C for each character 
to transmit. Note that locations 109H through 
1FFH of the PIP memory image are not used and 
can be replaced by special purpose drivers 
using DDT (see the DDT operator’s manual). 


PRN: Same as LST:, except that tabs are expanded 
at every eighth character position, lines are 
numbered, and page ejects are inserted every 
60 lines, with an initial eject (same as [t8np)). 


File and device names can be interspersed in the PIP commands. 
In each case, the specific device is read until end-of-file (ctl-Z for 
ASCII files, and a real end of file for non-ASCII disk files). Data 
from each device or file is concatenated from left to right until 

the last data source has been read. The destination device or file Is 
written using the data from the source files, and an end-of-file 
character (ctl-Z) is appended to the result for ASCII files. Note that 
if the destination is a disk file, a temporary file is created ($$$ 
secondary name) which is changed to the actual file name only 
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upon successful completion of the copy. Files with the extension 
“COM” are always assumed to be non-ASCll. 


The copy operation can be aborted at any time by depressing any 
key on the keyboard (a rubout suffices). PIP will respond with the 
message “ABORTED” to indicate that the operation was not 
completed. Note that if any operation is aborted, or if an error 
occurs during processing, PIP removes any pending commands 
which were set up while using the SUBMIT command. 


It should also be noted that PIP performs a special function if the 
destination is a disk file with type “HEX” (an Intel hex formatted 
machine code file), and the source is an external peripheral 
device, such as a paper tape reader. In this case, the PIP program 
checks to ensure that the source file contains a properly formed 
hex file, with legal hexadecimal values and checksum records. 
When an invalid input record is found, PIP reports an error 
message at the console and waits for corrective action. For 
convenience, PIP allows the end-of-file to be entered from the 
console if the source file is a RDR: device. In this case, the PIP 
program reads the device and monitors the keyboard. If ctl-Z is 
typed at the keyboard, then the read operation is terminated 
normally. 


Valid PIP commands are shown below. 


PIP LST: = X.PRN <cr> Copy X.PRN to the LST device and 
terminate the PIP program. 


PIP <cr> Start PIP for a sequence of commands 
(PIP prompts with “*”). 


*CON: = X.ASM,Y.ASM,Z.ASM <cr> 
Concatenate three ASM files and 
copy to the CON device. 


*X HEX = CON:,Y.HEX,PTR: <cr> 
Create a HEX file by reading CON 
(until a ctl-Z is typed), followed by 
data from Y.HEX, followed by data 
from PTR until a ctl-Z is encountered. 


*< Of Single carriage return stops PIP. 
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PIP PUN: = NUL:,X.ASM,EOF:,NUL: <cr> 
Send 40 nulls to the punch device; 
then copy the X.ASM file to the 
punch, followed by an end-of-file 
(ctl-Z) and 40 more null characters. 


The user can also specify one or more PIP parameters, enclosed in 
left and right square brackets, separated by zero or more blanks. 
Each parameter affects the copy operation, and the enclosed list of 
parameters must immediately follow the affected file or device. 
Generally, each parameter can be followed by an optional decimal 
integer value (the S and Q parameters are exceptions). The valid 
PIP parameters are listed below. 


B Block mode transfer: data is buffered by PIP until 
an ASCII x-off character (ctl-S) received from the 
source device. This allows transfer of data to a 
disk file from a continuous reading device, such 
as a cassette reader. Upon receipt of the x-off, 
PIP clears the disk buffers and returns for more 
input data. The amount of data which can be 
buffered is dependent upon the memory size of 
the host system (PIP will issue an error message 
if the buffers overflow). 


Dn Delete characters which extend past column n in 
the transfer of data to the destination from the 
character source. This parameter is used most 
often to truncate long lines which are sent to a 
(narrow) printer or console device. 


E Echo all transfer operations to the console as 
they are being performed. 
F Filter form feeds from the file. All imbedded 


form feeds are removed. The P parameter can be 
used simultaneously to insert new form feeds. 
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Pn 


QsTz 


Get file from user number n. (n is the range 
0-15.) Allows one user area to receive data files 
from another. If the operator has issued the 
USER 4 command at the CCP level, the 

PIP statement 


PIP X.Y = X.Y[G2] 


reads file X.Y from user number 2 into user area 
number 4. You cannot copy files into a different 
area than the one which is currently addressed 
by the USER command. 


Hex data transfer: all data is checked for proper 
Intel hex file format. Non-essential characters 
between hex records are removed during the 
copy operation. The console will be prompted for 
corrective action in case errors occur. 


Ignore “:00” records in the transfer of Intel 
hex format file (the | parameter automatically 
sets the H parameter). 


Translate upper case alphabetics to lower case. 


Add line numbers to each line transferred to 

the destination, starting at one, and incrementing 
by 1. Leading zeroes are suppressed, and the 
number is followed by a colon. If N2 is specified, 
then leading zeroes are included, and a tab Is 
inserted following the number. The tab Is 
expanded if T is set. 


Object file (non-ASCII) transfer: the normal 
CP/M end of file is ignored. 


Include page ejects at every n lines (with an 
initial page eject). If n = 1 or is excluded 
altogether, page ejects occur every 60 lines. If 
the F parameter is used, form feed suppression 
takes place before the new page ejects are 
inserted. 


Quit copying from the source device or file 
when the string s (terminated by ctl-Z) is 
encountered. 
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R Read system files. Allows files with the system 
attribute to be included in PIP transfers. 
Otherwise, system files are not recognized. 


SsTz Start copying from the source device when 
the string s is encountered (terminated by ctl-Z). 
The S and Q parameters can be used to 
“abstract” a particular section of a file (Such as 
a subroutine). The start and quit strings are always 
included in the copy operation. 


Note 


The strings following the s and q parameters are translated 
to upper case by the CCP if form (2) of the PIP command 
is used. Form (1) of the PIP invocation, however, does not 
perform the automatic upper case translation. 


(1) PIP <cr> 
(2) PIP “command line’ <cr> 


Tn Expand tabs (ctl-| characters) to every nth column 
during the transfer of characters to the 
destination from the source. 


U Translate lower case alphabetics to upper case 
during the copy operation. 


V Verify that data has been copied correctly by 
rereading after the write operation (the 
destination must be a disk file). 


W Write over R/O files without console interrogation. 
Under a normal operation, PIP will not 
automatically overwrite a file which is set to 
a permanent R/O status. It advises the user of 
the R/O status and waits for overwrite approval. 
W allows the user to bypass this interrogation 
process. 


Z Zero the parity bit on input for each 
ASCII character. 
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The following are valid PIP commands which specify parameters 
in the file transfer: 


PIP X.ASM = B:[v] <cr> Copy X.ASM from drive B to the 
current drive and verify that the data 
was properly copied. 


PIP LST: = X.ASM[nt8u] <cr> 
Copy X.ASM to the LST: device; 
number each line, expand tabs to 
every eighth column, and translate 
lower case alphabetics to upper case. 


PIP PUN: = X.HEX[I],Y.ZOT[h] <cr> 
First copy X.HEX to the PUN: device 
and ignore the trailing “:00” record 
in X.HEX; then continue the transfer 
of data by reading Y.ZOT, which 
contains hex records, including any 
“:00” records which it contains. 


PIP X.LIB = Y.ASM [sSUBR1:1z qgJUMP L37z] <cr> 
Copy from the file Y.ASM into the file 
X.LIB. Start the copy when the string 
“SUBR1:” has been found, and quit 
copying after the string ‘JUMP L3” is 
encountered. 


PIP LST: = X.ASM[p50] Send X.ASM to the LST: device, with 
line numbers, tabs expanded to every 
eighth column, and page ejects at 
every 50th line. Note that nt8p60 is 
the assumed parameter list for a LST 
file; p50 overrides the default value. 
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Note that the PIP program itself is initially copied to a user area (so 
that subsequent files can be copied) using the SAVE command. 
The sequence of operations shown below effectively moves PIP 
from one user area to the next. 


GBEERERERBRBSBEEBEEHEEEREEAE SE SE 


: 


ee es em 


. 


J 


SB BaBSE 


Sm 


J 


Introduction 


USER 0 login user O 

DDT PIPR.COM load PIP in memory 
(note PIP size s) 

GO return to CCP 
USER 3 login user 3 


SAVE s PIP.com 


where s is the integral number of memory “pages” (256 byte 
segments) occupied by PIP. The number s can be determined 
when PIP.COM is located under DDT, by referring to the value 
under the “NEXT” display. If for example, the next available 
address is 1D00, then PIP-COM requires 1C hexadecimal pages (or 
1 times 16+12 = 28 pages), and thus the value of s is 28 in the 
subsequent save. Once PIP is copied in this manner, it can then be 
copied to another disk belonging to the same user number 
through normal PIP transfers. 


ED 


The ED program is the CP/M system context editor, which allows 
creation and alteration of ASCII files in the CP/M environment. 
Complete details of operation are given in Chapter 3 CP/M ED. In 
general, ED allows the operator to create and operate upon 

source files which are organized as a sequence of ASCII characters, 
separated by end-of-line characters (a carriage-return line-feed 
sequence). There is no practical restriction on line length (no single 
line can exceed the size of the working memory), which Is 

instead defined by the number of characters typed between <cr>’s. 
The ED program has a number of commands for character string 
searching, replacement, and insertion, which are useful in the 
creation and correction of programs or text files under CP/M. 
Although the CP/M has a limited memory work space area, 

the file size which can be edited is not limited, since data is easily 
“paged” through this work area. 


Upon initiation, ED creates the specified source file, if it does not 
exist, and opens the file for access. The programmer then 
“appends’ data from the source file into the work area, if the 
source file already exists (see the A command), for editing. The 
appended data can then be displayed, altered, and written from the 
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work area back to the disk (see the W command). Particular 
points in the program can be automatically paged and located by 
context (see the N command), allowing easy access to particular 
portions of a large file. | 


Given that the operator has typed 
ED X.ASM <cr> 

the ED program creates an intermediate work file with the name 
X.$$$ 


to hold the edited data during the ED run. Upon completion of ED, 
the X.ASM file (original file) is renamed to X.BAK, and the edited 
work file is renamed to X.ASM. Thus, the X.BAK file contains the 
original (unedited) file, and the X.ASM file contains the newly 
edited file. The operator can always return to the previous version 
of a file by removing the most recent version, and renaming the 
previous version. Suppose, for example, that the current X.ASM 
file was improperly edited; the sequence of CCP commands 
shown below would reclaim the backup file. 


DIR X.* Check to see that BAK file is 
available. 
ERA X.ASM Erase most recent version. 


REN X.ASM = X.BAK Rename the BAK file to ASM. 


Note that the operator can abort the edit at any point (reboot, 
power failure, ctl-C, or Q command) without destroying the original 
file. In this case, the BAK file is not created, and the original file 

is always intact. 


The ED program also allows the user to ‘ping-pong’ the source and 
create backup files between two disks. The form of the ED 
command in this case is 

ED ufn d: 


where ufn is the name of a file to edit on the currently logged disk 
and d is the name of an alternate drive. The ED program reads 
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and processes the source file, and writes the new file to drive d, 
using the name ufn. Upon completion of processing, the original 
file becomes the backup file. Thus, if the operator is addressing 

disk A, the following command is valid: 


ED X.ASM B: 


which edits the file X.ASM on drive A, creating the new file 

X.$$$ on drive B. Upon completion of a successful edit, A:X.ASM is 
renamed to A:X.BAK, and B:X.$$$ is renamed to B:X.ASM. For 
user convenience, the currently logged disk becomes drive B at 
the end of the edit. Note that if a file by the name B:X.ASM 

exists before the editing begins, the message 


FILE EXISTS 


is printed at the console as a precaution against accidentally 
destroying a source file. In this case, the operator must first 
ERAse the existing file and then restart the edit operation. 


Similar to other transient commands, editing can take place ona 
drive different from the currently logged disk by preceding the 
source file name by a drive name. Examples of valid edit requests 
are shown below 


ED A:X.ASM Edit the file X.ASM on drive A, 
with new file and backup on 
drive A. 

ED B:X.ASM A: Edit the file X. ASM on drive B 


to the temporary file X.$$$ on 
drive A. On termination of 
editing, change X.ASM on drive 
B to X.BAK, and change X.$$$ 
on drive A to X.ASM. 


ED takes file attributes into account. If the operator attempts to 
edit a read/only file, the message 


**FILE IS READ/ONLY** 


appears at the console. The file can be loaded and examined, but 
cannot be altered in any way. Normally the operator simply ends 
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the edit session, and uses STAT to change the file attribute to R/W. 
If the edited file has the system attribute set, the message 


“SYSTEM” FILE NOT ACCESSIBLE 


is displayed at the console, and the edit session is aborted. 
Again, the STAT program can be used to change the system 
attribute if desired. 


SUBMIT 


The SUBMIT command allows CP/M commands to be batched 
together for automatic processing. The format of SUBMIT is: 


SUBMIT ufn parm #1...parm #n<cr> 


The ufn given in the SUBMIT command must be the filename of 
a file which exists on the currently logged disk, with an assumed 
file type of “SUB.” The SUB file contains CP/M prototype 
commands, with possible parameter substitution. The actual 
parameters parm #1 ... parm #n are substituted into the prototype 
commands, and, if no errors occur, the file of substituted 
commands is processed sequentially by CP/M. 


The prototype command file is created using the ED program, with 
interspersed “$” parameters of the form 


$1 $2 $3... $n 


corresponding to the number of actual parameters which will be 
included when the file is submitted for execution. When the SUBMIT 
transient is executed, the actual parameters parm #1 ... parm #n 
are paired with the formal parameters $1 ...$n in the prototype 
commands. If the number of formal and actual parameters does 

not correspond, then the submit function is aborted with an error 
message at the console. The SUBMIT function creates a file of 
substituted commands with the name 


$$$.SUB 


on the logged disk. When the system reboots (at the termination of 
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the SUBMIT), this command file is read by the CCP as a source 
of input, rather than the console. If the SUBMIT function is 
performed on any disk other than drive A, the commands are not 
processed until the disk is inserted into drive A and the system 
reboots. Further, the user can abort command processing at any 
time by typing a rubout when the command is read and echoed. In 
this case, the $$$.SUB file is removed, and the subsequent 
commands come from the console. Command processing is also 
aborted if the CCP detects an error in any of the commands. 
Programs which execute under CP/M can abort processing of 
command files when error conditions occur by simply erasing 
any existing $$$.SUB file. 


In order to introduce dollar signs into a SUBMIT file, the user may 
type a “$$” which reduces to a single “$” within the command 

file. Further, an up-arrow symbol “t” may precede an alphabetic 
character x, which produces a single ctl-x character within the 
file. 


The last command in a SUB file can initiate another SUB file, thus 
allowing chained batch commands. 
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Suppose the file ASMBL.SUB exists on disk and contains the 
prototype commands 


ASM $1 

DIR $1.* 

ERA *.BAK 

PIP $2 = $1.PRN 
ERA $1.PRN 


and the command 
SUBMIT ASMBL X PRN <cr> 
is issued by the operator. The SUBMIT program reads the 


ASMBL.SUB file, substituting “X” for all occurrences of $1 and 
“PRN” for all occurrences of $2, resulting in a $$$.SUB file 


pHREEREEREBEEBE A GE 


42 CP/M Reference Manual 


containing the commands 


ASM X 

DIR X.”* 

ERA *.BAK 

PIP PRN: = X.PRN 
ERA X.PRN 


which are executed in sequence by the CCP. 


The SUBMIT function can access a SUB file which is on an alternate 
drive by preceding the file name by a drive name. Submitted 

files are only acted upon, however, when they appear on drive A. 
Thus, it is possible to create a submitted file on drive B which is 
executed at a later time when it is inserted in drive A. 


XSUB 


XSUB extends the power of the SUBMIT facility to include character 
input during program execution as well as entering command 

lines. The XSUB command is included as the first line of your 
submit file and, when executed, self-relocates directly below the 
CGP. 


All subsequent submit command lines are processed by XSUB, so 
that programs which read buffered console input (BDOS function 
10) receive their input directly from the submit file. For example, 
the file SAVER.SUB could contain the submit lines: 


XSUB 

DDT 

I$1.HEX 

R 

GO 

SAVE 1 $2.COM 


with a subsequent SUBMIT command: 
SUBMIT SAVER X Y 


which substitutes X for $1 and Y for $2 in the command stream. 
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The XSUB program loads, followed by DDT which is sent the 
command lines “IX.HEX’ “R” and “GO,” thus returning to the CCP. 
The final command “SAVE 1 Y.COM’” is processed by the CCP. 


The XSUB program remains in memory, and prints the message 
(xsub active) 


on each warm start operation to indicate its presence. Subsequent 
submit command streams do not require the XSUB, unless an 
intervening cold start has occurred. Note that XSUB must be 
loaded after DESPOOL, if both are to run simultaneously. 


DUMP 


The DUMP program types the contents of the disk file (ufn) at the 
console in hexadecimal form. The file contents are listed sixteen 
bytes at a time, with the absolute byte address listed to the left of 
each line in hexadecimal. Long typeouts can be aborted by 
pushing the rubout key during printout. (The source listing of the 
DUMP program is given in the “CP/M Interface Guide” as an 
example of a program written for the CP/M environment.) 


BDOS Error Messages 


There are three error situations which the Basic Disk Operating 
System intercepts during file processing. When one of these 
conditions is detected, the BDOS prints the message: 


BDOS ERR ON x: error 


where x is the drive name, and “error” is one of the three error 
messages: 


BAD SECTOR 
SELECT 
R/O 


The “BAD SECTOR” message indicates that the disk controller 
electronics has detected an error condition in reading or writing 
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the diskette. This condition is generally due to a malfunctioning 
disk controller, or an extremely worn diskette. If you find that 

your system reports this error more than once a month, you should 
check the state of your controller electronics, and the condition 

of your media. In any case, recovery from this condition is 
accomplished by typing a ctl-C to reboot (this is the safest!), or a 
return, which simply ignores the bad sector in the file operation. 
Note, however, that typing a return may destroy your diskette 
integrity if the operation is a directory write, so make sure you 
have adequate backups in this case. 


The “SELECT” error occurs when there ts an attempt to address a 
drive beyond the A through D range. In this case, the value of x in 
the error message gives the selected drive. The system reboots 
following any input from the console. 


The R/O (read only) message occurs when there is an attempt to 
write to a diskette which has been designated as read-only ina 
STAT command, or has been set to read-only by the BDOS. In 
general, the operator should reboot CP/M either by using the 
warm start procedure ctl-C or by performing a cold start whenever 
the diskettes are changed. If a changed diskette is to be read but 
not written, BDOS allows the diskette to be changed without the 
warm or cold start, but internally marks the drive as read-only. 
The status of the drive is subsequently changed to read/write for 
input from the console. An automatic warm start takes place 
following any input. 


BEREEEESESE & 


BHREEEEEES EEE E 


7 


7 


pisacacnennsansiseannenRisttS 


45 


CP/M 2.0 Interface Guide 


ion Summary 


3 
= 
S 
@ 
© 
= 
2 
= 
S 


lon 


Introduct 
Sample File Dump Utility 
84 Sample Random Access Program 


CP/M 2. 


50 Operating System Call Conventions 
78 Sample File-to-File Copy Program 


92 System Funct 


46 
81 


soatatoctensnsny 


46 CP/M Reference Manual 


2 
CP/M 2.0 Interface Guide 


Introduction 


This manual describes CP/M, release 2, system organization 
including the structure of memory and system entry points. The 
intention is to provide the necessary information required to write 
programs which operate under CP/M, and which use the peripheral 
and disk I/O facilities of the system. 


CP/M is logically divided into four parts, called the Basic I/O 
System (BIOS), the Basic Disk Operating System (BDOS), the 
Console command processor (CCP), and the Transient Program 
Area (TPA). The BIOS is a hardware-dependent module which 
defines the exact low level interface to a particular computer 
system which is necessary for peripheral device I/O. The BIOS and 
BDOS are logically combined into a single module with a common 
entry point, and referred to as the FDOS. The CCP is a distinct 
program which uses the FDOS to provide a human-oriented 
interface to the information which is cataloged on the backup 
storage device. The TPA is an area of memory (i.e., the portion 
which is not used by the FDOS and CCP) where various non- 
resistant operating system commands and user programs are 
executed. The lower portion of memory is reserved for system 
information and Is detailed in later sections. 
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Memory organization of the CP/M system Is shown below: 


high memory 


FDOS (BDOS + BIOS} 
FBASE: 


CBASE: 


TPA 


system parameters 


TBASE: 


BOOT: 
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Base addresses for the two Apple memory configurations that 
can be used with CP/M are shown in the table below: 


Module 44K 56K (Language Card) 


CCP 9400H C400H 
BDOS 9COOH CCOOH 
BIOS AAOOH DAOOH 
Top of RAM AFFFH DEPrr 


All standard CP/M versions assume BOOT=OOOOH, which is the 
base of random access memory. The machine code found at 
location BOOT performs a system ‘warm start” which loads and 
initializes the programs and variables necessary to return control 
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to the CCP. Thus, transient programs need only jump to location 
BOOT to return control to CP/M at the command level. Further, 
the standard versions assume TBASE=BOOT+0100H which is 
normally location 0100H. The principal entry point to the FDOS 
is at location BOOT+0005H (normally OOO5H) where a jump to 
FBASE is found. The address field at BOOT+0006H (normally 


OOO6H) contains the value of FBASE and can be used to determine 


the size of available memory, assuming the CCP is being 
overlayed by a transient program. 


Transient programs are loaded into the TPA and executed as 
follows. The operator communicates with the CCP by typing 
command lines following each prompt. Each command line takes 
one of the forms: 


command 
command file1 
command file1 file2 


where “command” is either a built-in function such as DIR or 
TYPE, or the name of a transient command or program. If the 


command is a built-in function of CP/M, it is executed immediately. 


Otherwise, the CCP searches the currently addressed disk for a 
file by the name 


command.COM 


If the file is found, it is assumed to be a memory image of a 
program which executes in the TPA, and thus implicitly originates 
at TBASE in memory. The CCP loads the COM file from the disk 
into memory starting at TBASE and possibly extending up to 
CBASE. 


If the command is followed by one or two file specifications, the 
CCP prepares one or two file control block (FCB) names in the 
system parameter area. These optional FCB’s are in the form 
necessary to access files through the FDOS, and are described 
in the next section. 
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The transient program receives control from the CCP and begins 
execution, perhaps using the I/O facilities of the FDOS. The 
transient program is “called” from the CCP, and thus can simply 
return to the CCP upon completion of its processing, or can jump 
to BOOT to pass control back to CP/M. In the first case, the 
transient program must not use memory above CBASE, while in 
the latter case, memory up through FBASE-1 is free. 


The transient program may use the CP/M I/O facilities to 
communicate with the operator's console and peripheral devices, 
including the disk subsystem. The I/O system is accessed by 
passing a ‘function number” and an “information address” to CP/M 
through the FDOS entry point at BOOT+O05H. In the case of a 
disk read, for example, the transient program sends the number 
corresponding to a disk read, along with the address of an FCB 

to the CP/M FDOS. The FDOS, in turn, performs the operation and 
returns with either a disk read completion indication or an error 
number indicating that the disk read was unsuccessful. The function 
numbers and error indicators are given below. 
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Operating System Call Conventions 


The purpose of this section is to provide detailed information for 
performing direct operating system calls from user programs. 


CP/M facilities which are available for access by transient 
programs fall into two general categories: simple device I/O, and 
disk file |/O. The simple device operations include: 


Read a Console Character 

Write a Console Character 

Read a Sequential Tape Character 
Write a Sequential Tape Character 
Write a List Device Character 

Get or Set I/O Status 

Print Console Buffer 

Read Console Buffer 

Interrogate Console Ready 


The FDOS operations which perform disk Input/Output are 


Disk System Reset 

Drive Selection 

File Creation 

File Open 

File Close 

Directory Search 

File Delete 

File Rename 

Random or Sequential Read 
Random or Sequential Write 
Interrogate Available Disks 
Interrogate Selected Disk 
Set DMA Address 
Set/Reset File Indicators 


As mentioned above, access to the FDOS functions is accomplished 
by passing a function number and information address through 

the primary entry point at location BOOT+O005H. In general, the 
function number Is passed in register C with the information 
address in the double byte pair DE. Single byte values are returned 
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in register A, with double byte values returned in HL (a zero 
value is returned when the function number is out of range). For 
reasons of compatibility, register A=L and register B=H upon 
return in all cases. The CP/M function numbers are: 


O System Reset 19 Delete File 

1 Console Input 20 Read Sequential 

2 Console Output 21 Write Sequential 

3 Reader Input 22 Make File 

4 Punch Output 23 Rename File 

5 List Output 24 Return Login Vector 
6 Direct Console I/O 25 Return Current Disk 
7 Get I/O Byte 26 Set DMA Address 
8 Set 1/O Byte 2/7 Get Addr (Alloc) 

9 Print String 28 Write Protect Disk 
10 Read Console Buffer 29 Get R/O Vector 

11 Get Console Status 30 Set File Attributes 
12 Return Version Number 31 Get Addr (Disk Parms) 
13 Reset Disk System 32 Set/Get User Code 
14 Select Disk 33 Read Random 

15 Open File 34 Write Random 
16 Close File 35 Compute File Size 
17 Search for First 36 Set Random Record 


18 Search for Next 


(Functions 28 and 32 should be avoided in application programs to 
maintain upward compatibility with MP/M.) 


Upon entry to a transient program, the CCP leaves the stack 
pointer set to an eight level stack area with the CCP return address 
pushed onto the stack, leaving seven levels before overflow 
occurs. Although this stack is usually not used by a transient 
program (i.e., most transients return to the CCP through a jump 

to location OOOOH), it is sufficiently large to make CP/M system 
calls since the FDOS switches to a local stack at system entry. 
The following assembly language program segment, for example, 
reads characters continuously until an asterisk is encountered, at 
which time control returns to the CCP (assuming a standard CP/M 
system with BOOT+Q00O00H): 
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BDOS EQU OO05H ;STANDARD CP/M ENTRY 
CONIN EQU 1 ;CONSOLE INPUT FUNCTION 
ORG 0100H sBASE OF TPA 
NEXTC: MVI C,CONIN  ;READ NEXT CHARACTER 
CALL BDOS “RETURN CHARACTER IN <A> 
CPI = ;-END OF PROCESSING? 
JNZ NEXTC sLOOP IF NOT 
Rel -RETURN TO CCP 
END 


CP/M implements a named file structure on each disk, providing a 
logical organization which allows any particular file to contain 

any number of records from completely empty to the full capacity 
of the drive. Each drive is logically distinct with a disk directory 
and file data area. The disk file names are in three parts: the drive 
select code, the file name consisting of one to eight non-blank 
characters, and the file type consisting of zero to three non-blank 
characters. The file tyoe names the generic category ora 
particular file, while the file name distinguishes individual files in 
each category. The file types listed below name a few generic 
categories which have been established, although they are generally 
arbitrary: 


ASM_ Assembler Source PLI PL/I Source File 

PRN _ Printer Listing REL Relocatable Module 
HEX Hex Machine Code TEX TEX Formatter Source 
BAS Basic Source File BAK ED Source Backup 
INT Intermediate Code SYM SID Symbol File 

COM CCPCommand File $$$ Temporary File 


Source files are treated as a sequence of ASCII characters, where 
each ‘line’ of the source file is followed by a carriage-return 
line-feed sequence (ODH followed by OAH). Thus one 128 byte 
CP/M record could contain several lines of source text. The end 
of an ASCII file is denoted by a control-Z character (1AH) or a real 
end of file, returned by the CP/M read operation. Control-Z 
characters embedded within machine code files (e.g., COM files) 
are ignored, however, and the end of file condition returned by 
CP/M is used to terminate read operations. 
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Files in CP/M can be thought of as a sequence of up to 65536 
records of 128 bytes each, numbered from O through 65535, 

thus allowing a maximum of 8 megabytes per file. Note, however, 
that although the records may be considered logically contiguous, 
they may not be physically contiguous in the disk data area. 
Internally, all files are broken into 16K byte segments called 
logical extents, so that counters are easily maintained as 8-bit 
values. Although the decomposition into extents is discussed in 
the paragraphs which follow, they are of no particular consequence 
to the programmer since each extent is automatically accessed 

in both sequential and random access modes. 


In the file operations starting with function number 15, DE usually 
addresses a file control block (FCB). Transient programs often 

use the default file control block area reserved by CP/M at location 
BOOT+005CH (normally OO5CH) for simple file operations. The 
basic unit of file information is a 128 byte record used for all file 
operations, thus a default location for disk I/O is provided by 

CP/M at location BOOT+0080H (normally OO080H) which is the 
initial default DMA address (see function 26). All directory 
operations take place in a reserved area which does not affect 
write buffers as was the case in release 1, with the exception of 
Search for First and Search for Next, where compatibility 

is required. 


The File Control Block (FCB) data area consists of a sequence of 
33 bytes for sequential access and a series of 36 bytes in the 

case that the file is accessed randomly. The default file control 
block normally located at OO5CH can be used for random access 
files, since the three bytes starting at BOOT+007DH are available 
for this purpose. The FCB format is shown with the following fields: 
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00 01 02... 08 O9 10 11 12 13 14 15 16... 31 32 33 34 35 


04 
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dr 


ig Pree is. 


1,12, 3 


€X 


S1 
S2 
rc 
dO...dn 


Cr 


ro. Tt.fZ 


drive code (0 - 16) 

O=> use default drive for file 
1=>auto disk select drive A, 
2=> auto disk select drive B, 


16=>auto disk select drive P. 


contain the file name in ASCII upper case, 
with high bit=o 


contain the file type in ASCII upper case, 


with high bit=O 
t1’,t2’, and t3’ denote the bit of these 
positions, 


t1’=1=>Read/Only file, 
t2’=1=>SYS file,no DIR list 


contains the current extent number, 
normally set to OO by the user, but in range 
0 - 31 during file 1/O 


reserved for internal system use 


reserved for internal system use, set to zero 
on call to OPEN, MAKE, SEARCH 


record count for extent “ex,” takes on values 
from 0 - 128 


filled-in by CP/M, reserved for system use 


current record to read or write ina 
sequential file operation, normally set to 
zero by user 


optional random record number in the range 
0-65535, with overflow to r2, rO, r1 constitute 
a 16-bit value with low byte rO, and high 

byte r1 
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Each file being accessed through CP/M must have a corresponding 
FCB which provides the name and allocation information for all 
subsequent file operations. When accessing files, it is the 
programmer's responsibility to fill the lower sixteen bytes of the 
FCB and initialize the “cr” field. Normally, bytes 1 through 11 are 
set to the ASCII character values for the file name and file type, 
while all other fields are zero. 


FCB’s are stored in a directory area of the disk, and are brought 
into central memory before proceeding with file operations (see 
the OPEN and MAKE functions). The memory copy of the FCB is 
updated as file operations take place and later recorded permanently 
on disk at the termination of the file operation (see the CLOSE 
command). 


The CCP constructs the first sixteen bytes of two optional FCB’s for 
a transient by scanning the remainder of the line following the 
transient name, denoted by “‘file1” and “file2” in the prototype 
command line described above, with unspecified fields set to 

ASCII blanks. The first FCB is constructed at location BOOT+005CH, 
and can be used as-is for subsequent file operations. The second 
FCB occupies the d). . . dn portion of the first FCB, and must be 
moved to another area of memory before use. If, for example, 

the operator types 


PROGNAME B:X.ZOT Y.ZAP 


the file PROGNAME. COM is loaded into the TPA, and the default 
FCB at BOOT+O05CH is initialized to drive code 2, file name “xX” 
and file type “ZOT.’ The second drive code takes the default value 
O, which is placed at BOOT+O06CH, with the file name “Y” 

placed into location BOOT+O0O6DH and file type “ZAP” located 8 
bytes later at BOOT+0075H. All remaining fields through ‘“‘cr’”’ 

are set to zero. Note again that it is the programmer's responsibility 
to move this second file name and type to another area, usually a 
separate file control block, before opening the file which begins at 
BOOT+0O05CH, due to the fact that the open operation will 
overwrite the second name and type. 


If no file names are specified in the original command, then the 
fields beginning at BOOT+005DH and BOOT+O06DH contain 
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blanks. In all cases, the CCP translates lower case alphabetics to 
upper case to be consistent with the CP/M file naming 
conventions. 


As an added convenience, the default buffer area at location 
BOOT+O080H is initialized to the command line tail typed by the 
operator following the program name. The first position contains 
the number of characters, with the characters themselves following 
the character count. Given the above command line, the area 
beginning at BOOT+O080H is initialized as follows: 


BOOT+0080H: 
+00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +10 +11 +12 +13 +14 
(A ee Ae a ee ee ey ee ye ee 


where the characters are translated to upper case ASCII with 
uninitialized memory following the last valid character. Again, it 
is the responsibility of the programmer to extract the information 
from this buffer before any file operations are performed, unless 
the default DMA address is explicitly changed. 


The individual functions are described in detail in the pages which 
follow. 


Function 0: System Reset 


Entry Parameters: 
Register C: OOH 


The system reset function returns control to the CP/M operating 
system at the CCP level. The CCP re-initializes the disk subsystem 
by selecting and logging-in disk drive A. This function has exactly 
the same effect as a jump to location BOOT. 
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Function 1: Console Input 


Entry Parameters: 
Register C: O1H 


Returned Value: 
Register A: ASCII Character 


The console input function reads the next console character to 
register A. Graphic characters, along with carriage return, line 
feed, and backspace (ctl-H) are echoed to the console. Tab 
characters (ctl-l) are expanded in columns of eight characters. A 
check is made for start/stop scroll (ctl-S) and start/stop printer 
echo (ctl-P). The FDOS does not return to the calling program 
until a character has been typed, thus suspending execution of a 
character if not ready. 


Function 2: Console Output 


Entry Parameters: 
Register C: 02H 
Register E: ASCII Character 


The ASCII character from register E is sent to the console 
device. Similar to function 1, tabs are expanded and checks are 
made for start/stop scroll and printer echo. 


Function 3: Reader Input 


Entry Parameters: 
Register C: O3H 


Returned Value: 
Register A: ASCII Character 
The Reader Input function reads the next character from the 


logical reader into register A. Control does not return until the 
character has been read. 
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Function 4: Punch Output 


Entry Parameters: 


Register C: 04H 
Register E: ASCII Character 


The Punch Output function sends the character from register E to 
the logical punch device. 


Function 5: List Output 


Entry Parameters: 


Register CG; 05h 
Register E: ASCII Character 


The List Output function sends the ASCII character in register E to 
the logical listing device. 


Function 6: Direct Console I/O 


Entry Parameters: 


Register C: O6H 
Register E: OFFH (input) or 
char (output) 


Returned Value: 


Register A: char or status 
(no value) 


Direct console I/O is supported under CP/M for those specialized 
applications where unadorned console input and output is 
required. Use of this function should, in general, be avoided since 
it bypasses all of CP/M’s normal control character functions (e.g., 
control-S and control-P). Programs which perform direct I/O through 
the BIOS under previous releases of CP/M, however, should be 
changed to use direct |/O under BDOS so that they can be fully 
supported under future releases of MP/M and CP/M. 
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Upon entry to function 6, register E either contains hexadecimal 
FF, denoting a console input request, or register E contains an 
ASCII character. If the input value is FF, then function 6 returns 
A=00 if no character is ready, otherwise A contains the next 
console input character. 


If the input value in E is not FF, then function 6 assumes that E 
contains a valid ASCII character which is sent to the console. 


Function 7: Get 1/O Byte 


Entry Parameters: 
Register C: O7H 


Returned Value: 
Register A: |/O Byte Value 


The Get I/O Byte function returns the current value of IOBYTE in 
register A. 


Function 8: Set 1/O Byte 


Entry Parameters: 


Register C: O8H 
Register E: I/O Byte Value 


The Set I/O Byte function changes the system IOBYTE value to 
that given in register E. 


Function 9: Print String 


Entry Parameters: 


Register C: OOH 
Registers DE: String Address 


The Print String function sends the character string stored In 
memory at the location given by DE to the console device, until a 
“$” is encountered in the string. Tabs are expanded as In function 
2, and checks are made for start/stop scroll and printer echo. 


99 
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Function 10: Read Console Buffer 


Entry Parameters: 
Register C: OAH 
Registers DE: Buffer Address 
Returned Value: 
Console Characters in Buffer 
The Read Buffer function reads a line of edited console input 
into a buffer addressed by registers DE. Console input is terminated 


when either the input buffer overflows. The Read Buffer takes 
the form: 


DE, +0 +1 42 43 74 TO 76 TF TC aes FN 


where “mx” is the maximum number of characters which the buffer 
will hold (1 to 255), ‘nc’ is the number of characters read (set by 
FDOS upon return), followed by the characters read from the 
console. If nc < mx, then uninitialized positions follow the last 
character, denoted by “??” in the above figure. A number of control 
functions are recognized during line editing: 


rub/del removes and echoes the last character 
ctl-C reboots when at the beginning of line 
ctl-E causes physical end of line 

ctl-H backspaces one character position 

ctl-J (line feed) terminates input line 

ctl-M (return) terminates input line 

ctl-R retypes the current line after new line 
ctl-X backspaces to beginning of current line 


Note also that certain functions which return the carriage to the 
leftmost position (e.g., ctl-X) do so only to the column position 
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where the prompt ended (in earlier releases, the carriage returned 
to the extreme left margin). This convention makes operator data 
input and line correction more legible. 


Function 11: Get Console Status 


Entry Parameters: 
Register C: OBH 


Return Value: 


Register A: Console Status 


The Console Status function checks to see if a character has been 
typed at the console. If a character is ready, the value OFFH is 
returned in register A. Otherwise a OOH value is returned. 


Function 12: Return Version Number 


Entry Parameters: 
Register C: OCH 


Returned Value: 


Registers © HL: Version Number 


Function 12 provides information which allows version independent 
programming. A two-byte value is returned, with H=O00 designating 
the CP/M release (H=01 for MP/M), and L=O0 for all releases 
previous to 2.0. CP/M 2.0 returns a hexadecimal 20 in register L, 
with subsequent version 2 releases in the hexadecimal range 21, 
22, through 2F. Using function 12, for example, you can write 
application programs which provide both sequential and random 
access functions, with random access disabled when operating 
under early releases of CP/M. 
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Function 13: Reset Disk System 


Entry Parameters: 
Register C: ODH 


The Reset Disk function is used to programmatically restore the 
file system to a reset state where all disks are set to read/write 
(see functions 28 and 29), only disk drive A is selected, and the 
default DMA address is reset to BOOT+O080H. This function can 
be used, for example, by an application program which requires a 
disk change without a system reboot. 


Function 14: Select Disk 


Entry Parameters: 


Register G: OEH 
Register E: Selected Disk 


The Select Disk function designates the disk drive named in 
register E as the default disk for subsequent file operations, with 
E=0 for drive A, 1 for drive B, and so-forth through 15 corresponding 
to drive P in a full sixteen drive system. The drive is placed in an 
“on-line” status which, in particular, activates its directory until the 
next cold start, warm start, or disk system reset operation. If the 
disk media is changed while it is on-line, the drive automatically 
goes to a read/only status in a standard CP/M environment (see 
function 28). FCB’s which specify drive code zero (dr=O0OH) 
automatically reference the currently selected default drive. 

Drive code values between 1 and 16, however, ignore the selected 
default drive and directly reference drives A through P. 
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Function 15: Open File 


Entry Parameters: 


Register Cc: OFH 
Registers DE: FCB Address 


Returned Value: 
Register A: Directory Code 


The Open File operation is used to activate a file which currently 
exists in the disk directory for the currently active user number. 
The FDOS scans the referenced disk directory for a match in 
positions 1 through 14 of the FCB referenced by DE (byte s1 is 
automatically zeroed), where an ASCII question mark (3FH) 
matches any directory character in any of these positions. 
Normally, no question marks are included and, further, bytes “ex” 
and ‘“s2” of the FCB are zero. 


If a directory element is matched, the relevant directory information 
is copied into bytes dO through dn of the FCB, thus allowing 
access to the files through subsequent read and write operations. 
Note that an existing file must not be accessed until a successful 
open operation is completed. Upon return, the open function 
returns a ‘directory code’ with the value O through 3 if the open 
was successful, or OFFH (255 decimal) if the file cannot be found. 
If question marks occur in the FCB then the first matching FCB 

is activated. Note that the current record (‘cr’) must be zeroed by 
the program if the file is to be accessed sequentially from the 
first record. 
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Function 16: Close File 


Entry Parameters: 


Register C: 10H 
Registers DE: FCB Address 


, 


Returned Value: 
Register A: Directory Code 


i 


The Close File function performs the inverse of the open file 
function. Given that the FCB addressed by DE has been previously 
activated through an open or make function (see functions 15 

and 22), the close function permanently records the new FCB in 
the referenced disk directory. The FCB matching process for the 
close is identical to the open function. The directory code returned 
for a successful close operation is O, 1, 2, or 3, while a OFFH 

(255 decimal) is returned if the file name cannot be found in the 
directory. A file need not be closed if only read operations have 
taken place. If write operations have occurred, however, the close 
operation is necessary to permanently record the new directory 
information. 


= EE 


Function 17: Search for First 


Entry Parameters: 


Register CG tH 
Registers DE: FCB Address 


Returned Value: 


Register A: Directory Code 


Search for First scans the directory for a match with the file given 
by the FCB addressed by DE. The value 255 (hexadecimal FF) is 
returned if the file is not found, otherwise O, 1, 2, or 3 is returned 
indicating the file is present. In the case that the file is found, the 
current DMA address is filled with the record containing the 
directory entry, and the relative starting position is A *382 (1.e., 
rotate the A register left 5 bits, or ADD A five times). Although 
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a6 
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not normally required for application programs, the directory 
information can be extracted from the buffer at this position. 


An ASCII question mark (63 decimal, 3F hexadecimal) in any 
position from “f1” through “ex” matches the corresponding field of 
any directory entry on the default or auto-selected disk drive. If 

the ‘dr’ field contains an ASCII question mark, then the auto disk 
selected function is disabled, the default disk is searched, with 

the search function returning any matched entry, allocated or free, 
belonging to any user number. This latter function is not normally 
used by application programs, but does allow complete flexibility to 
scan all current directory values. If the “dr” field is not a question 
mark, the ‘“s2” byte is automatically zeroed. 


Function 18: Search for Next 


Entry Parameters: 
Register C: 12H 


Returned Value: 

Register A: Directory Code 
The Search for Next function is similar to the Search for First 
function, except that the directory scan continues from the last 


matched entry. Similar to function 17, function 18 returns the decimal 
value 255 in Awhen no more directory items match. 


Function 19: Delete File 


Entry Parameters: 

Register CG: 1Shi 

Registers DE: FCB Address 
Returned Value: 

Register A: Directory Code 


The Delete File function removes files which match the FCB 
addresses by DE. The filename and type may contain ambiguous 
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references (I.e., question marks in various positions), but the drive 
select code cannot be ambiguous, as in the Search and Search for 
Next functions. 


Function 19 returns a decimal 255 if the referenced file or files 
cannot be found, otherwise a value in the range O to 3 is 
returned. 


Function 20: Read Sequential 


Entry Parameters: 


Register C: 14H 
Registers DE: FCB Address 


Returned Value: 


Register A: Directory Code 


Given that the FCB addressed by DE has been activated through 
an open or make function (numbers 15 and 22), the Read Sequential 
function reads the next 128 byte record from the file into memory 
at the current DMA address. The record is read from position “cr” 
of the extent, and the ‘cr’ field is automatically incremented to 

the next record position. If the ‘cr’ field overflows then the next 
logical extent is automatically opened and the “cr” field is reset 

to zero in preparation for the next read operation. The value OOH is 
returned in the A register if the read operation was successful, 
while a non-zero value is returned if no data exists at the next 
record position (e.g., end of file occurs). 


Function 21: Write Sequential 


Entry Parameters: 
Register CG: 15H 
Registers DE: FCB Address 
Returned Value: 


Register A: Directory Code 
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J 


Given that the FCB addressed by DE has been activated through 
an open or make function (numbers 15 and 22), the Write 
Sequential function writes the 128 byte data record at the current 
DMA address to the file named by the FCB. The record is placed 
at position ‘cr’ of the file, and the “cr” field is automatically 
incremented to the next record position. If the ‘cr’ field overflows 
then the next logical extent is automatically opened and the ‘cr’ 
field is reset to zero in preparation for the next write operation. 
Write operations can take place into an existing file, in which case 
newly written records overlay those which already exist in the 
file. Register A=OOH upon return from a successful write operation, 
while a non-zero value indicates an unsuccessful write due to a 
full disk. 


a om 


a 


Function 22: Make File 
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Entry Parameters: 


Register G: 16H 
Registers DE: FCB Address 


J 


Returned Value: 


Register A: Directory Code 


The Make File operation is similar to the open file operation 
except that the FCB must name a file which does not exist in the 
currently referenced disk directory (i.e., the one named explicitly 
by a non-zero “dr’ code, or the default disk if “dr” is zero). The 
FDOS creates the file and initializes both the directory and main 
memory value to an empty file. The programmer must ensure that 
no duplicate file names occur, and a preceding delete operation 
is sufficient if there is any possibility of duplication. Upon return, 
register A=O, 1, 2, or 3 if the operation was successful and OFFH 
(255 decimal) if no more directory space is available. The make 
function has the side-effect of activating the FCB and thus a 
subsequent open Is not necessary. 
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Function 23: Rename File 


Entry Parameters: 


Register | ifr 
Registers DE: FCB Address 


Returned Value: 
Register A: Directory Code 


The Rename function uses the FCB addressed by DE to change 
all occurrences of the file named in the first 16 bytes to the file 
named in the second 16 bytes. The drive code “dr” at position O 
is used to select the drive, while the drive code for the new file 
name at position 16 of the FCB is assumed to be zero. Upon 
return, register A is set to a value between O and 3 if the rename 
was successful, and OFFH (255 decimal) if the first file name 
could not be found in the directory scan. 


Function 24: Return Login Vector 


Entry Parameters: 
Register C: 18H 


Returned Value: 
Registers | HL: Login Vector 


The login vector value returned by CP/M is a 16-bit value in HL, 
where the least significant bit of L corresponds to the first drive 
A, and the high order bit of H corresponds to the sixteenth drive, 
labelled P.A ‘“O” bit indicates that the drive is not on-line, while a 
“1” bit marks a drive that is actively on-line due to an explicit disk 
drive selection, or an implicit drive select caused by a file 
operation which specified a non-zero ‘dr’ field. Note that 
compatibility is maintained with earlier releases, since registers A 
and L contain the same values upon return. 
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Function 25: Return Current Disk 


Entry Parameters: 
Register C: 19H 


Returned Value: 


Register A: Current Disk 


Function 25 returns the currently selected default disk number 
in register A. The disk numbers range from O through 15 
corresponding to drives A through P. 


Function 26: Set DMA Address 


Entry Parameters: 


Regular C: 1AH 
Registers DE: DMA Address 


“DMA’ is an acronym for Direct Memory Address, which is often 
used in connection with disk controllers which directly access the 
memory of the mainframe computer to transfer data to and from 
the disk subsystem. Although many computer systems use non-DMA 
access (i.e., the data is transferred through programmed I/O 
operations), the DMA address has, in CP/M, come to mean the 
address at which the 128 byte data record resides before a disk 
write and after a disk read. Upon cold start, warm start, or disk 
system reset, the DMA address is automatically set to 
BOOT+0O080H. The Set DMA function, however, can be used to 
change this default value to address another area of memory where 
the data records reside. Thus, the DMA address becomes the 
value specified by DE until it is changed by a subsequent Set DMA 
function, cold start, warm start, or disk system reset. 
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Function 27: Get ADDR (ALLOC) 


Entry Parameters: 
Register C: 1BH 


Returned Value: 
Registers | HL: ALLOC Address 


An “allocation vector” is maintained in main memory for each 
on-line disk drive. Various system programs use the information 
provided by the allocation vector to determine the amount of 
remaining storage (see the STAT program). Function 27 returns the 
base address of the allocation vector for the currently selected 
disk drive. The allocation information may, however, be invalid if 
the selected disk has been marked read/only. Although this 
function is not normally used by application programs, additional 
details of the allocation vector are found in the “CP/M Alteration 
Guide.” 


Function 28: Write Protect Disk 


Entry Parameters: 


Register CG: TCH 
The disk write protect function provides temporary write protection 
for the currently selected disk. Any attempt to write to the disk, 
before the next cold or warm start operation produces the message 


Bdos Err on d: R/O 
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Function 29: Get Read/Only Vector 


Entry Parameters: 
Register CG: 1DH 


Returned Value: 
Registers ~ HL: R/O Vector Value 


Function 29 returns a bit vector in register pair HL which indicates 
drives which have the temporary read/only bit set. Similar to 
function 24, the least significant bit corresponds to drive A, while 
the most significant bit corresponds to drive P. The R/O bit is set 
either by the explicit call to function 28, or by the automatic 
software mechanisms within CP/M which detect changed disks. 


Function 30: Set File Attributes 


Entry Parameters: 


Register CG: IE 
Registers DE: FCB Address 


Returned Value: 


Register A: Directory Code 


The Set File Attributes function allows programmatic manipulation 
of permanent indicators attached to files. In particular, the R/O 
and System attributes (t1’ and t2’) can be set or reset. The DE pair 
addresses an unambiguous file name with the appropriate 
attributes set or reset. Function 30 searches for a match, and 
changes the matched directory entry to contain the selected 
indicators. Indicators f1’ through f4’ are not presently used, but 
may be useful for applications programs, since they are not 
involved in the matching process during file open and close 
operations. Indicators f5’ through f8’ and t3’ are reserved for 
future system expansion. 
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Function 31: Get ADDR (Disk PARMS) 


Entry Parameters: 
Register Cc TFA 


Returned Value: 
Registers | HL: DPB Address 


The address of the BIOS resident disk parameter block is returned 
in HL as a result of this function call. This address can be used 

for either of two purposes. First, the disk parameter values can be 
extracted for display and space computation purposes, or transient 
programs can dynamically change the values of current disk 
parameters when the disk environment changes, if required. 
Normally, application programs will not require this facility. 


Function 32: Set/Get User Code 


Entry Parameters: 


Register GC: 20h 
Register E: OFFH (get) or 
User Code (set) 


Returned Value: 


Register A: Current Code or 
(no value) 


An application program can change or interrogate the currently 
active user number by calling function 32. If register E=OFFH, then 
the value of the current user number is returned in register A, 
where the value is in the range 0 to 31. If register E is not OFFH, 
then the current user number is changed to the value of E 

(modulo 32). 
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Function 33: Read Random 


Entry Parameters: 


Register Ce 211A 
Registers DE: FCB Address 


Returned Value: 
Register A: Return Code 


The Read Random function is similar to the sequential file read 
operation of previous releases, except that the read operation 
takes place at a particular record number, selected by the 24-bit 
value constructed from the three byte field following the FCB (byte 
positions rO at 33, r1 at 34, and r2 at 35). Note that the sequence 

of 24 bits is stored with least significant byte first (rO), middle byte 
next (r1), and high byte last (r2). CP/M does not reference byte 

r2, except in computing the size of a file (function 35). Byte r2 must 
be zero, however, since a non-zero value indicates overflow past 
the end of file. 


Thus, the rO,r1 byte pair is treated as a double-byte, or “word” 
value, which contains the record to read. This value ranges from 

O to 65535, providing access to any particular record of the 8 
megabyte file. In order to process a file using random access, 

the base extent (extent 0) must first be opened. Although the base 
extent may or may not contain any allocated data, this ensures 
that the file is properly recorded in the directory, and is visible in 
DIR requests. The selected record number is then stored into 

the random record field (rO,r1), and the BDOS is called to read the 
record. Upon return from the call, register A either contains an 
error code, as listed below, or the value OO indicating the operation 
was successful. In the latter case, the current DMA address 
contains the randomly accessed record. Note that contrary to the 
sequential read operation, the record number is not advanced. 
Thus, subsequent random read operations continue to read the 
same record. 
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Upon each random read operation, the logical extent and current 
record values are automatically set. Thus, the file can be sequentially 
read or written, starting from the current randomly accessed 
position. Note, however, that in this case, the last randomly read 
record will be re-read as you switch from random mode to 
sequential read, and the last record will be re-written as you switch 
to a sequential write operation. You can, of course, simply 

advance the random record position following each random read or 
write to obtain the effect of a sequential |/O operation. 


Error codes returned in Register A following a random read are 
listed below. 


O1 reading unwritten data 

02 (not returning in random mode) 
O03 cannot close current extent 

04 seek to unwritten extent 

O05 (not returned in read mode) 

O06 seek past physical end of disk 


Error code 01 and 04 occur when a random read operation accesses 
a data block which has not been previously written, or an extent 
which has not been created, which are equivalent conditions. Error 
3 does not normally occur under proper system operation, but 

can be cleared by simply re-reading, or re-opening extent zero as 
long as the disk is not physically write protected. Error code 06 
occurs whenever byte r2 is non-zero under the current 2.0 release. 
Normally, non-zero return codes can be treated as missing data, 
with zero return codes indicating operation complete. 


ea 


BERERESESBEEESE & 


EEE 


7 


BEESH SE 


J 


igagEaSaEE: & 


588 


J 


i 8 


J 


CP/M 2.0 Interface Guide 15 


Function 34: Write Random 


Entry Parameters: 


Register GC: 2en 
Registers DE: FCB Address 


Returned Value: 
Register A: Return Code 


The Write Random operation is initiated similar to the Read 
Random call, except that data Is written to the disk from the current 
DMA address. Further, if the disk extent or data block which is 

the target of the write has not yet been allocated, the allocation is 
performed before the write operation continues. As in the Read 
Random operation, the random record number is not changed as a 
result of the write. The logical extent number and current record 
positions of the file control block are set to correspond to the 
random record which is being written. Again, sequential read or 
write operations can commence following a random write, with the 
notation that the currently addressed record is either read or 
rewritten again as the sequential operation begins. You can also 
simply advance the random record position following each write 

to get the effect of a sequential write operation. Note that in 
particular, reading or writing the last record of an extent in 

random mode does not cause an automatic extent switch as it does 
in sequential mode. 


The error codes returned by a random write are identical to the 
random read operation with the addition of error code 05, which 
indicates that a new extent cannot be created due to directory 
overflow. 
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Function 35: Compute File Size 


Entry Parameters: 


Register GC 23r 
Registers DE: FCB Address 


Returned Value: 
Random Record Field Set 


When computing the size of a file, the DE register pair addresses 
an FCB in random mode format (bytes rO, r1, and r2 are present). 
The FCB contains an unambiguous file name which is used in 

the directory scan. Upon return, the random record bytes contain 
the “virtual” file size which is, in effect, the record address of the 
record following the end of the file. If, following a call to function 
35, the high record byte r2 is 01, then the file contains the 
maximum record count 65536. Otherwise, bytes rO and r1 constitute 
a 16-bit value (rO is the least significant byte, as before) which is 
the file size. 


Data can be appended to the end of an existing file by simply 
calling function 35 to set the random record position to the end 

of file, then performing a sequence of random writes starting at the 
preset record address. 


The virtual size of a file corresponds to the physical size when 
the file is written sequentially. If, instead, the file was created in 
random mode and “holes” exist in the allocation, then the file 
may in fact contain fewer records than the size indicates. If, for 
example, only the last record of an eight megabyte file is written 
in random mode (i.e., record number 65535), then the virtual size 
in 65536 records, although only one block of data is actually 
allocated. 
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Function 36: Set Random Record 


Entry Parameters: 


Register Cy 24A 
Registers DE: FCB Address 


Returned Value: 
Random Record Field Set 


The Set Random Record function causes the BDOS to automatically 
produce the random record position from a file which has been 
read or written sequentially to a particular point. The function can 
be useful in two ways. 


First, it is often necessary to initially read and scan a sequential 
file to extract the position of various “key” fields. As each key is 
encountered, function 36 is called to compute the random record 
position for the data corresponding to this key. If the data unit size 
is 128 bytes, the resulting record position is placed into a table 
with the key for later retrieval. After scanning the entire file and 
tabularizing the keys and their record numbers, you can move 
instantly to a particular keyed record by performing a random read 
using the corresponding random record number which was saved 
earlier. The scheme is easily generated when variable record 
lengths are involved since the program need only store the 
buffer-relative byte position along with the key and record number 
in order to find the exact starting position of the keyed data at a 
later time. 


A second use of function 36 occurs when switching from a 
sequential read or write over to random read or write. A file is 
sequentially accessed to a particular point in the file, function 36 is 
called which sets the record number, and subsequent random 

read and write operations continue from the selected point in the 
file. 
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Sample File-to-File Copy Program 


The program shown below provides a relatively simple example of 
file operations. The program source file is created as COPY.ASM 
using the CP/M ED program and then assembled using ASM or 
MAC, resulting in a “HEX” file. The LOAD program is then used 

to produce a COPY.COM file which executes directly under the 
CCP. The program begins by setting the stack pointer to a local 
area, and then proceeds to move the second name from the default 
area at OO6CH to a 33-byte file control block called DFCB. The 
DFCB is then prepared for file operations by clearing the current 
record field. At this point, the source and destination FCB’s are 
ready for processing since the SFCB at OO5CH is properly set-up 
by the CCP upon entry to the COPY program. That is, the first 
name is placed into the default FCB, with the proper fields zeroed, 
including the current record field at OO7CH. The program 
continues by opening the source file, deleting any existing 
destination file, and then creating the destination file. If all this is 
successful, the program loops at the label COPY until each 

record has been read from the source file and placed into the 
destination file. Upon completion of the data transfer, the destination 
file is closed and the program returns to the CCP command level 
by jumping to BOOT. 


SAMPLE FILE-TO-FILE COPY PROGRAM 
AT THE CCP LEVEL, THE COMMAND 
COPY A:X.Y B:U.V 


COPIES THE FILE NAMED X.Y FROM DRIVE 
A TOAFILE NAMED U.V ON DRIVE B. 


0000 BOOT EQU 0000H - SYSTEM REBOOT 


0005 = BDOS EQU O0005H ; BDOS ENTRY POINT 
005C = FCB1 EQU 005CH ; FIRST FILE NAME 
005C = SFCB EQU FCB1 ; SOURCE FCB 

OO6C = FCB2 EQU OO6CH ; SECOND FILE NAME 
0080 = DBUFF EQU 0080H ; DEFAULT BUFFER 
0100 = TPA EQU 0100H ; BEGINNING OF TPA 
0009 = PRINTF EQU S ; PRINT BUFFER FUNC# 
OOOF = OPENF EQU 15 ; OPEN FILE FUNC# 
0010 = CLOSEF EQU 16 ; CLOSE FILE FUNC# 
0013 = DELETEF EQU 19 ; DELETE FILE FUNC# 
0014 = READF EQU 20 >; SEQUENTIAL READ 
0015 = WRITEF EQU 21 >; SEQUENTIAL WRITE 
0016 = MAKEF EQU Ze ; MAKE FILE FUNC# 
0100 ORG TPA - BEGINNING OF TPA 


0100 311B02 LXI| SP,STACK ; LOCAL STACK 
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0169 


C20B01 


AF 
32FA01 


115C00 
CD6901 


CC6101 


11DA01 
CD7301 


11DA01 
CD8201 


CC6101 


115C00 
CD7801 
B7 

C25101 


11DA01 
CD7D01 
11A901 
B7 
C46101 
C33701 


11DA01 
CD6E01 


CC6101 


11CCO1 


OEO9 
CDO500 
C30000 


OEOF 


MFCB: 


COPY: 


EOFILE: 


OPEN: 
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MOVE SECOND FILE NAME TO DFCB 


MVI C,16 ; HALF AN FCB 

LXI| D,FCB2 ; SOURCE OF MOVE 
LXI| H,DFCB ; DESTINATION FCB 
LDAX D ; SOURCE FCB 

INX D ; READY NEXT 

MOV M,A , DEST FCB 

INX H ; READY NEXT 

DCR C ; COUNT 16...0 
JNZ MFCB ; LOOP 16 TIMES 
NAME HAS BEEN MOVED, ZERO CR 

XRA A ; A=0O0H 

STA DFCBCR ; CURRENT REC =0 


SOURCE AND DESTINATION FCB’S READY 


LXI| D,SFCB ; SOURCE FILE 

CALL OPEN ; ERROR IF 255 

LX| D,NOFILE ; READY MESSAGE 
INR A ; 255 BECOMES 0 

CZ FINIS ; DONE IF NO FILE 
SOURCE FILE OPEN, PREP DESTINATION 

LXI| D,DFCB ; DESTINATION 

CALL DELETE ; REMOVE IF PRESENT 
LXI| D,DFCB ; DESTINATION 

CALL MAKE ; GREATE THE FILE 

LXI| D,NODIR) ; READY MESSAGE 
INR A ; 255 BECOMES 0 

CZ FINIS ; DONE IF NO DIR SPACE 


SOURCE FILE OPEN, DEST FILE OPEN 
COPY UNTIL END OF FILE ON SOURCE 


LX| D,SFCB ; SOURCE 

CALL READ ; READ NEXT RECORD 

ORA A ; END OP FILE? 

JNZ EOFILE ; SKIP WRITE IF SO 

NOT END OF FILE, WRITE THE RECORD 

LXI| D,DFCB ; DESTINATION 

CALL WRITE ; WRITE RECORD 

LXI| D,SPACE ; READY MESSAGE 

ORA A ; OO IF WRITE OK 

CNZ FINIS ; ENDIF SO 

JMP COPY ; LOOP UNTIL EOF 
END OF FILE, CLOSE DESTINATION 

LX! D,DFCB ; DESTINATION 

CALL CLOSE ; 2695 IF ERROR 

LXI| H,WRPROT ; READY MESSAGE 

INR A ; 255 BECOMES 00 

CZ FINIS ; SHOULDN'T HAPPEN 

COPY OPERATION COMPLETE, END 

LXI D,NORMAL ; READY MESSAGE 
WRITE MESSAGE GIVEN BY DE, REBOOT 

MVI C,PRINTF 

CALL BDOS WRITE MESSAGE 

JMP BOOT REBOOT SYSTEM 


SYSTEM INTERFACE SUBROUTINES 
(ALL RETURN DIRECTLY FROM BDOS) 


MVI C,OPENF 
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016B C30500 JMP BDOS 
O16E OE10 CLOSE: MVI C.CLOSEF 
0170 C30500 JMP BDOS 
0173 0E13 DELETE: MVI C.DELETEF 
0175 C30500 JMP BDOS 
0178 OE14 READ: MVI C.READF 
017A C30500 JMP BDOS 
017D OE15 WRITE: — MVI C.WRITEF 
017F C30500 JMP BDOS 
0182 OE16 MAKE: MVI C.MAKEF 
0184 C30500 JMP BDOS 
CONSOLE MESSAGES 
0187 6E6F20FNOFILE: DB ‘NO SOURCE FILES: 
0196 6E6F209NODIR: DB ‘NO DIRECTORY SPACES: 
O1A9 6F7574FSPACE: DB ‘OUT OF DATA SPACES: 
01BB 7772695WRPROT: DB WRITE PROTECTED?$° 
O1CC 636F700NORMAL: DB COPY COMPLETES: 
DATA AREAS 
O1DA DFECB: DS 33 DESTINATION FCB 
O1FA = DFCBCR EQU DFCB+32 : CURRENT RECORD 
O1FB . DS 32 - 16 LEVEL STACK 
STACK: 
021B END 


Note that there are several simplifications in this particular 
program. First, there are no checks for invalid file names which 
could, for example, contain ambiguous references. This situation 
could be detected by scanning the 32 byte default area starting at 
location OO5CH for ASCII question marks. A check should also 

be made to ensure that the file names have, in fact, been included 
(check locations OO5DH and OO6DH for non-blank ASCII characters). 
Finally, a check should be made to ensure that the source and 
destination file names are different. A soeed improvement could be 
made by buffering more data on each read operation. One could, 
for example, determine the size of memory by fetching FBASE 
from location OOO6H and use the entire remaining portion of 
memory for a data buffer. In this case, the programmer simply 
resets the DMA address to the next successive 128 byte area 
before each read. Upon writing to the destination file, the DMA 
address is reset to the beginning of the buffer and incremented 

by 128 bytes to the end as each record is transferred to the 
destination file. 
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Sample File Dump Utility 


The file dump program shown below is slightly more complex 

than the single copy program given in the previous section. The 
dump program reads an input file, specified in the CCP command 
line, and displays the content of each record in hexadecimal format 
at the console. Note that the dump program saves the CCP’s 

stack upon entry, resets the stack to a local area, and restores the 
CCP’s stack before returning directly to the CCP. Thus, the dump 
program does not perform warm start at the end of processing. 


; DUMP PROGRAM READS INPUT FILE AND DISPLAYS HEX DATA 


"sSSenunanenuuunauauauaas 


0100 ORG 100H 
0005 = BDOS EQU 0005H ‘DOS ENTRY POINT 
0001 = CONS EQU 1 -READ CONSOLE 
Co0e: = TYPEF EQU 2 ‘TYPE FUNCTION 
0009 = PRINTF  EQU 9 ‘BUFFER PRINT ENTRY 
00OB = BRKF EQU 11 -BREAK KEY FUNCTION (TRUE IF CHAR) 
OOOF = OPENF EQU 15 -FILE OPEN 
| 0014 = READF EQU 20 -READ FUNCTION 
605C = FCB EQU 5CH -FILE CONTROL BLOCK ADDRESS 
0080 = BUFF EQU 80H -INPUT DISK BUFFER ADDRESS 
NON GRAPHIC CHARACTERS 
O0OD = CR EQU ODH ‘CARRIAGE RETURN 
OOOA = LF EQU OAH -LINE FEED 
| FILE CONTROL BLOCK DEFINITIONS 
005C = FCBDN EQU FCB+0 ‘DISK NAME 
005D = FCBFN EQU FCB+1 -FILE NAME 
| 0065 = FCBFT EQU FCB+9 -DISK FILE TYPE (3 CHARACTERS) 
0068 = FCBRL EQU FCB+12  -:FILE'SS CURRENT REEL NUMBER 
006B = FCBRC EQU FCB+15 — :-FILE‘SS RECORD COUNT (0 TO 128) 
| oO7G. = FCBCR EQU FCB+32  :>CURRENT(NEXT) RECORD NUMBER (0) 
| 007D = FCBLN  EQU FCB+33.  ;>FCBLENGTH 
SET UP STACK 
0100 210000 LXI H,O 
| 0103 39 DAD SP 
ENTRY STACK POINTER IN HL FROM THE CCP 
| 0104 221502 SHLD OLDSP 
| SET SP TO LOCAL STACK AREA (RESTORED AT FINIS) 
ea 0107 315702 LXI SPSTKTOP 
| READ AND PRINT SUCCESSIVE BUFFERS 
| 010A CDC101 CALL SETUP ‘SET UP INPUT FILE 
- 010D FEFF CPI 255 255 IF FILE NOT PRESENT 
O10F C21B01 JNZ OPENOK _ :SKIPIF OPEN IS OK 
Pe : FILE NOT THERE, GIVE ERROR MESSAGE AND RETURN 
| 0112 LLF301 LXI D,OPNMSG 
| 0115 CD9CO1 CALL ERR 
| — 0118 C35101 JMP FINIS ‘TO RETURN 
| OPENOK: :;OPEN OPERATION OK, SET BUFFER INDEX TO END 
| 011B 3E80 MvVI A.80H 
ry 011D 321302 STA IBP ‘SET BUFFER POINTER TO 80H 
| ; HL CONTAINS NEXT ADDRESS TO PRINT 
| 0120 210000 LXI H.O ‘START WITH 0000 
] 
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0159 
015C 
O15E 
0161 
0164 


0165 
0168 
016A 
016B 
O16E 
0171 


0172 
0174 
0177 
0179 
017C 


ES 
CDA201 
E1 
DA5101 
47 


7D 
E60F 
C24401 


CD7201 


CD5901 


OF 
DA5101 


CD8FO1 
C32301 


CD7201 
2A1502 
F9 


CQ 


E5D5C5 
OEOB 
CDO500 
C1D1E1 
C9 


ES5D5C5 


GLOOP: 


NONUM: 


FINIS: 


BREAK: 


PCHAR: 


CRLF: 


PUSH H “SAVE LINE POSITION 

CALL GNB 

POP H “RECALL LINE POSITION 

JC FINIS ‘CARRY SET BY GNB IF END FILE 


MOV BA 
PRINT HEX VALUES 
CHECK FOR LINE FOLD 


MOV A,L 
ANI OFH -CHECK LOW 4 BITS 
JNZ NONUM 


PRINT LINE NUMBER 
CALL CRLF 


CHECK FOR BREAK KEY 
CALL BREAK 
ACCUM LSB = 1 IF CHARACTER READY 


RRC -INTO CARRY 

JC FINIS ‘DON'T PRINT ANY MORE 
MOV A,H 

CALL PHEX 

MOV A,L 

CALL PHEX 

INX H ‘TO NEXT LINE NUMBER 
MVI A, 

CALL PCHAR 

MOV A,B 

CALL PHEX 

JMP GLOOP 


END OF DUMP, RETURN TO CCP 

(NOTE THAT A JMP TO O0000H REBOOTS) 
CALL CRLF 

LHLD OLDSP 


SPHL 
STACK POINTER CONTAINS CCP’S STACK LOCATION 
RET 10 THE CCP 


SUBROUTINES 


-CHECK BREAK KEY (ACTUALLY ANY KEY WILL DO) 
PUSH H! PUSH D! PUSH B; ENVIRONMENT SAVED 
MVI C,BRKF 

CALL BDOS 

POP B! POP D! POP H; ENVIRONMENT RESTORED 
RET 


“PRINT A CHARACTER 

PUSH H! PUSH D! PUSH B; SAVED 
MVI C,TYPEr 

MOV E.A 

CALL BDOS 

POP B! POP D! POP H; RESTORED 


RET 

MVI A,CR 
CALL PCHAR 
MVI A,LF 
CALL PCHAR 
RET 
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E60F 
FEOA 
D28901 


C630 
C38B01 


C637 
CD6501 
C9 


OF 
CD7D01 
F4 
CD7D01 
cg 


OEO9 
CDO500 
C9 


3A1302 
FE80 
C2B301 


CDCEO1 
B7 
CAB301 


37 
C9 


321302 
218000 
19 
7E 


B7 
C9 


AF 
327C00 


115C00 
OEOF 


PNIB: 


ERR: 


GNB: 


Go: 


SETUP: 
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;PRINT NIBBLE IN REGA 


ANI OFH ;LOW 4 BITS 
CPI 10 

JNC P10 

LESS THAN OR EQUAL TO 9 

ADI 0 

JMP PRN 

GREATER OR EQUAL TO 10 

ADI ‘A’ — 10 

CALL PCHAR 

RET 

;PRINT HEX CHAR IN REG A 

PUSH PSW 

RRC 

RRC 

RRC 

RRC 

CALL PNIB ;PRINT NIBBLE 
POP PSW 

CALL PNIB 

RET 


;PRINT ERROR MESSAGE 
D,E ADDRESSES MESSAGE ENDING WITH “$" 


MVI C,PRINTF = ;PRINT BUFFER FUNCTION 
CALL BDOS 
RET 


(GET NEXT BYTE 


LDA IBP 
CPI 80H 
JNZ GO 


READ ANOTHER BUFFER 


CALL DISKR 

ORA A ;>ZERO VALUE IF READ OK 
JZ GO “FOR ANOTHER BYTE 

END OF DATA, RETURN WITH CARRY SET FOR EOF 
STC 

RET 


;READ THE BYTE AT BUFF+REGA 


MOV E,A -1S BYTE OF BUFFER INDEX 

MVI D,O ;DOUBLE PRECISION INDEX TO DE 
INR A INDEX=INDEX+1 

STA IBP ;BACK TO MEMORY 


POINTER IS INCREMENTED 
SAVE THE CURRENT FILE ADDRESS 


LXI| M,BUFF 

DAD D 

ABSOLUTE CHARACTER ADDRESS IS IN H1 
MOV A,M 

BYTE IS IN THE ACCUMULATOR 

ORA A ;-RESET CARRY BIT 
RET 

joel UP FILE 

OPEN THE FILE FOR INPUT 

XRA A ;ZERO TO ACCUM 
STA FCBCR ;CLEAR CURRENT RECORD 
LXI| D,FCB 

MVI C,OPENF 
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O1CA CDO500 CALL BDOS 
; 955 IN ACCUM IF OPEN ERROR 

O1CD C9 RET 
DISKR: | -READ DISK FILE RECORD 

O1CE ES5D5C5 PUSH H! PUSH D! PUSH B 

01D1 115C00 LXI D.FCB 

01D4 0OE14 MVI C.READF 

01D6 CDO500 CALL BDOS 

01D9 C1DI1E1 POP B! POP D! POPH 

O1DC C9 RET 
. FIXED MESSAGE AREA 

O1DD 46494COSIGNON: DB ‘FILE DUMP VERSION 2.08 

O1F3 ODOA4EOOPNMSG: DB CR LFE‘NO INPUT FILE PRESENT ON DISKS: 
. VARIABLE AREA 

0213 IBP: DS 2 -/NPUT BUFFER POINTER 

0215 OLDSP: DS 2 ‘ENTRY SP VALUE FROM CCP 
STACK AREA 

0217 DS 64 -RESERVE 32 LEVEL STACK 
STKTOP: 

0257 | END 


Sample Random Access Program 


This manual is concluded with a rather extensive, but complete 
example of random access operation. The program listed below 
performs the simple function of reading or writing random records 
upon command from the terminal. Given that the program has been 
created, assembled, and placed into a file labelled RANDOM.COM, 
the CCP level command: 


RANDOM X.DAT 
starts the test program. The program looks for a file by the name 
X.DAT (in this particular case) and, if found, proceeds to prompt the 
console for input. If not found, the file is created before the 
prompt is given. Each prompt takes the form 


next command? 


and is followed by operator input, terminated by a carriage return. 
The input commands take the form 


nw nR Q 


where n is an integer value in the range O to 65535, and W, R, 
and Q are simple command characters corresponding to random 
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write, random read, and quit processing, respectively. If the W 
command is issued, the RANDOM program issues the prompt 


type data: 


The operator then responds by typing up to 127 characters, followed 
by a carriage return. RANDOM then writes the character string 
into the X.DAT file at record n. If the R command is issued, 
RANDOM reads record number n and displays the string value at 
the console. If the Q command is issued, the X.DAT file is closed, 
and the program returns to the console command processor. In 
the interest of brevity, the only error message is 


error, try again 


The program begins with an initialization section where the input 
file is opened or created, followed by a continuous loop at the 
label “ready” where the individual commands are interpreted. The 
default file control block at OO5CH and the default buffer at 
OO80H are used in all disk operations. The utility subroutines then 
follow, which contain the principal input line processor, called 
“readc.’ This particular program shows the elements of random 
access processing, and can be used as the basis for further 
program development. 


i eee eee eee ee ee ee ee ee eee eee ee ee ee ee ee eee 
os * 


-+ SAMPLE RANDOM ACCESS PROGRAM FOR CP/M 20 * 
"ok * 
yO OOO kk 

0100 ORG 100H - BASE OF TPA 

0000 = REBOOT EQU 0000H - SYSTEM REBOOT 

0005 = BDOS EQU 0005H - BDOS ENTRY POINT 

0001 = CONINP — EQU 1 - CONSOLE INPUT FUNCTION 

0002 = CONOUT EQU 2 - CONSOLE OUTPUT FUNCTION 

0009 = PSTRING EQU 9 - PRINT STRING UNTIL '$’ 

000A = RSTRING EQU 10 - READ CONSOLE BUFFER 

000C = VERSION EQU 12 - RETURN VERSION NUMBER 

OOOF = OPENF  EQU 15 - FILE OPEN FUNCTION 

0010 = CLOSEF EQU 16 - CLOSE FUNCTION 

0016 = MAKEE — EQU 22 : MAKE FILE FUNCTION 

0021 = READR EQU 33 - READ RANDOM 

0022 = WRITER EQU 34 - WRITE RANDOM 

005C = FCB EQU 005CH - DEFAULT FILE CONTROL BLOCK 
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007D 
007F 
0080 


000D 
OOOA 


0137 
013A 
013D 
0140 
0142 
0144 


0147 
0149 
014C 
O14F 
0150 
0153 
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Hout tl 


RANREC 
RANOVE 
BUFF 
CR 

LF 


’ 


EQU 
EQU 
EQU 


EQU 
EQU 


FCB+33 - RANDOM RECORD POSITION 
FCB+35 - HIGH ORDER (OVERFLOW) BYTE 


0080H - BUFFER ADDRESS 
ODH - CARRIAGE RETURN 
OAH ; LINE FEED 


EERERRELERERARA EER EALREE EAA RERS HR ORERE EERE ES 


_* 


. * LOAD SP, SET-UP FILE FOR RANDOM ACCESS 


ed 
’ 


* 


* 


* 


[Phe oe EAEERAARE A ERRAE ELENA RH RD EERE PERS EOE R TOTS 


CALL 


VERSOK: 


JNZ 


LX SP,STACK 

VERSION 2.0? 

MVI C,VERSION 

BDOS 

CPI 20H - VERSION 2.0 OR BETTER? 
JNC VERSOK 

BAD VERSION, MESSAGE AND GO BACK 

LXI| D,BADVER 

CALL PRINT 

JMP REBOOT 


CORRECT VERSION FOR RANDOM ACCESS 


MVI C,OPENF ;OPEN DEFAULT FCB 

LXI| D,FCB 

CALL BDOS 

INR A - ERR 255 BECOMES ZERO 
JNZ READY 

CANNOT OPEN FILE, SO CREATE IT 

MVI C,MAKEF 

LX D,FCB 

CALL BDOS 

INR A - ERR 255 BECOMES ZERO 
READY 

CANNOT CREATE FILE, DIRECTORY FULL 

LXI| D,NOSPACE 

CALL PRINT 

JMP REBOOT ;BACK TO CCP 


’ 
CRREERRLEEEEREDE RE LERRARREDRER EEA EE ES OEE EERE EERE S® 


ae. 4 


* LOOP BACK TO “READY” AFTER EACH COMMAND 


. ¥ 
’ 


* 


* 


* 


PR EA RRR ERE EEE EERE ERR EERE ERE AR ER EE ES 


READY: 


’ 


FILE IS READY FOR PROCESSING 


CALL READCOM ;READ NEXT COMMAND 
SHLD RANREC  ; STORE INPUT RECORD# 
LX H,RANOVF 

MVI M,O -CLEAR HIGH BYTE IF SET 
CPI ‘Q’ ; QUIT? 

JNZ NOTQ 

QUIT PROCESSING, CLOSE FILE 

MVI C,CLOSEF 

LXI| D,FCB 

CALL BDOS 

INR A - ERR 255 BECOMES 0 

JZ ERROR - ERROR MESSAGE, RETRY 
JMP REBOOT ;BACK TO CCP 


ZL. 
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SR RR OO kk kkk kk kk kok kk ok ok kk kk ook 


= 


* 


;>* END OF QUIT COMMAND, PROCESS WRITE * 
* * 
‘ii ehenes bekeheesekeueetadieieesbiadndeeeteacss 
NOTQ: 
NOT THE QUIT COMMAND, RANDOM WRITE? 

CPI ‘W' 

JNZ NOTW 
THIS IS ARANDOM WRITE, FILL BUFFER UNTIL CR 

LX| D,DATMSG 

CALL PRINT - DATA PROMPT 

MVI C.t2¢ -UP TO 127 CHARACTERS 

LX| H,BUFF ‘DESTINATION 
RLOOP: > READ NEXT CHARACTER TO BUFF 

PUSH B > SAVE COUNTER 

PUSH H > NEXT DESTINATION 

CALL GETCHR “CHARACTER TOA 

POP H -RESTORE COUNTER 

POP B > RESTORE NEXT TO FILL 

CPI CR “END OF LINE? 

JZ ERLOOP 

NOT END, STORE CHARACTER 

MOV M.A 

INX H ‘NEAT TO FILL 

DCR  & ‘COUNTER GOES DOWN 

JNZ RLOOP > END OF BUFFER? 
ERLOOP: 
END OF READ LOOP, STORE 00 

MVI M,O 
: WRITE THE RECORD TO SELECTED RECORD NUMBER 

MVI C,WRITER 

LXI D,FCB 

CALL BDOS 

ORA A - ERROR CODE ZERO? 

JNZ ERROR > MESSAGE IF NOT 

JMP READY >FOR ANOTHER RECORD 
Crt e eed eCREee eS CHEW EDR RNOE GR oR ENede eee eRe 
bat 4 * 
-* END OF WRITE COMMAND, PROCESS READ * 
“ok * 
<CiCi eee COE eAe Hee ewe eee ec deereeeNeueesuates 
NOTW: 
NOT A WRITE COMMAND, READ RECORD? 

CPI ‘R’ 

JNZ ERROR SKIP IF NOT 

READ RANDOM RECORD 

MVI C,READR 

LXI| D.FCE 

CALL BDOS 

ORA A > RETURN CODE 00? 

JNZ ERROR 
READ WAS SUCCESSFUL, WRITE TO CONSOLE 

CALL CRLF “NEW LINE 

MVI leo > MAX 128 CHARACTERS 

LXI| H, BUFF > NEXT TO GET 
WLOOP: 

MOV A,M * NEXT CHARACTER 

INX H > NEXT TO GET 

ANI 7FH > MASK PARITY 


88 


01B9 
01BC 
O1BF 


01C2 
01C4 
01C7 


01C8 
01CA 
01CB 
01CE 


01CF 
01D1 
01D4 
01D6 
01D9 


01DA 
01DB 
01DE 
01DF 
O1E1 

O1E4 


01E5 
01E8 
01EB 
O1ED 
01FO 


O1F3 
O1F6 
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11590 
CDDAO 
C3370 


JZ READY “FOR ANOTHER COMMAND IF 00 
PUSH B ; SAVE COUNTER 

PUSH H > SAVE NEXT TO GET 

CPI i ; GRAPHIC? 

CNC PUTCHR - SKIP OUTPUT IF NOT 

POP H 

POP B 

DCR C ; COUNT=COUNT-1 

JNZ WLOOP 

JMP READY 


’ 
cavern enna even CCC Cn nn Gn hak 2b ab ae ae Se ee ee eee alee 


ok 
;* END OF 


ae 


’ 
’ 


READ COMMAND, ALL ERRORS END-UP HERE 


* 


* 


* 


RHR RR EERE RRR RARER ERE RE REE EERE EE EEE E ES 


ERROR: 


LXI| D,ERRMSG 
CALL PRINT 
JMP READY 


’ 
[PERE LELAEAARERALAARR HRKER EERE RES AA EERE CRESS SESH TS 


“ok 


* 


’ 


+ UTILITY SUBROUTINES FOR CONSOLE I/O 


* 


* 


* 


‘CERKRERLEE PAA EERA AREER AAA HE ERE REE ED SERENE AEE ES 


GETCHR: 


PUTCHR: 


CRLF: 


PRINT 


READCOM: 


- READ NEXT CONSOLE CHARACTER TO A 
MVI C,CONINP 


- WRITE CHARACTER FROM A TO CONSOLE 
MVI C,CONOUT 


MOV EA CHARACTER TO SEND 
CALL BDOS - SEND CHARACTER 
RET 


‘SEND CARRIAGE RETURN LINE FEED 


MVI A,CR - CARRIAGE RETURN 
CALL PUTCHR 

MVI A,LF -LINE FEED 

CALL PUTCHR 

RET 


- PRINT THE BUFFER ADDRESSED BY DE UNTIL $ 


PUSH D 

CALL CRLF 

POP D >; NEW LINE 

MVI C,PSTRING 

CALL BDOS > PRINT THE STRING 
RET 


- READ THE NEXT COMMAND LINE TO THE CONBUF 
LXI\ D,PROMPT 


CALL PRINT ; COMMAND? 
MVI C,RSTRING 
LX\ D,CONBUF 


CALL BDOS -READ COMMAND LINE 
COMMAND LINE IS PRESENT, SCAN IT 

LXI\ H,O - START WITH 0000 

LXI D,CONLIN ;COMMAND LINE 


Ef 


a 


EREHRESE & 
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O1F9 1A READC: LDAX  D - NEXT COMMAND CHARACTER | 
- O1FA 13 INX D TO NEXT COMMAND POSITION 
| O1FB B7 ORA A - CANNOT BE END OF COMMAND 
O1FC C8 RZ 
NOT ZERO, NUMERIC? 
| O1FD D630 SUI ‘0 ) 
| O1FF FEOA CPI 10 - CARRY IF NUMERIC | 
| 0201 D2130 JNC ENDRD 
| | ADD-IN NEXT DIGIT 
| 0204 29 DAD H 49 | 
0205 4D MOV on 
5 0206 44 MOV BH -BC = VALUE * 2 | 
| 0207 29 DAD H #4 | 
0208 29 DAD H “#8 
| 0209 09 DAD B +24 *B=*40 
| 020A 85 ADD 1 - +DIGIT 
| | 020B 6F MOV 1A 
| 020C D2F90 JNC READC —_: FOR ANOTHER CHAR 
. O20F 24 INR H “OVERFLOW 
| 0210 C3F90 JMP READC —:FOR ANOTHER CHAR 
ENDRD: 
- ; END OF READ, RESTORE VALUE IN A 
| 0213 C630 ADI 0 “COMMAND 
0215 FE61 CPI A - TRANSLATE CASE? 
0217 D8 RC 
| :; LOWER CASE, MASK LOWER CASE BITS | 
| 0218 E65F ANI 101$1111B 
021A C9 RET 
= III III IIIT III IOI tts 
| = ‘+ STRING DATA AREA FOR CONSOLE MESSAGE * 
q q ; * e 
EECA EEE ARES AEE EALEARAAEARE AES EAA EERE SK SE EO I 
BADVER: | 
| ry 021B 536F79 DB ‘SORRY, YOU NEED CP/M VERSION 28° 
| | NOSPACE: | 
023A 4E6F29 DB ‘NO DIRECTORY SPACES’ 
DATMSG: 
ey 024D 547970 DB ‘TYPE DATA: $° 
ERRMSG: | 
0259 457272 DB ‘ERROR, TRY AGAIN." 
PROMPT: 
026B 46570 DB ‘NEXT COMMAND? $' 


’ 
LEEEREERELAE ACERS RAREL ES RERER AEE ASRS EERE ESSERE SHE 


ke * 


Zea 


“+ FIXED AND VARIABLE DATA AREA , 
ok * 
th CKEERER RARE EREREREE ERE IRE REE REE EEE REESE REE ESD | 
O27A 21 CONBUF: DB CONLEN ; LENGTH OF CONSOLE BUFFER | 
027B CONSIZE: DS 1 - RESULTING SIZE AFTER READ 
027C CONLIN: DS 32 “LENGTH 32 BUFFER 
0021 = CONLEN EQU $-CONSIZ 
| 029C | DS 32 - 16 LEVEL STACK | 
STACK: | 
02BC END | 


i 


a 


| a 
rc 
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Again, major improvements could be made to this particular 
program to enhance its operation. In fact, with some work, this 
program could evolve into a simple data base management 
system. One could, for example, assume a standard record size of 
128 bytes, consisting of arbitrary fields within the record. A 
program, called GETKEY, could be developed which first reads a 
sequential file and extracts a specific field defined by the operator. 
For example, the command 


GETKEY NAMES.DAT LASTNAME 10 20 


would cause GETKEY to read the data base file NAMES.DAT and 
extract the “‘“LASTNAME?” field from each record, starting at 
position 10 and ending at character 20. GETKEY builds a table in 
memory consisting of each particular LASTNAME field, along 
with its 16-bit record number location within the file. The GETKEY 
orogram then sorts this list, and writes a new file, called 
LASTNAME.KEY, which is an alphabetical list of LASTNAME 
fields with their corresponding record numbers. (This list is called 
an “inverted index” in information retrieval parlance.) 


Rename the program shown above as QUERY, and massage it a 
bit so that it reads a sorted key file into memory. The command line 
might appear as: 


QUERY NAMES.DAT LASTNAME.KEY 


Instead of reading a number, the QUERY program reads an 
alohanumeric string which is a particular key to find in the 
NAMES.DAT data base. Since the LASTNAME.KEY list is sorted, 
you can find a particular entry quite rapidly by performing a 
“binary search,” similar to looking up a name in the telephone 
book. That is, starting at both ends of the list, you examine the 
entry halfway in between and, if not matched, split either the upper 
half or the lower half for the next search. You'll quickly reach the 
item you're looking for (in log2(n) steps) where you'll find the 
corresponding record number. Fetch and display this record at 
the console, just as we have done in the program shown above. 


At this point you’re just getting started. With a little more work, you 
can allow a fixed grouping size which differs from the 128 byte 


E 


7 
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record shown above. This is accomplished by keeping track of the 
record number as well as the byte offset within the record. 
Knowing the group size, you randomly access the record containing 
the proper group, offset to the beginning of the group within the | 
record read sequentially until the group size has been exhausted. | 


Finally, you can improve QUERY considerably by allowing boolean 
expressions which compute the set of records which satisfy 
several relationships, such as a LASTNAME between HARDY and 
LAUREL, and an AGE less than 45. Display all the records which 
fit this description. Finally, if your lists are getting too big to fit into 
memory, randomly access your key files from the disk as well. 

One note of consolation after all this work: if you make it through 
the project, you'll have no more need for this manual! 


BEBREB BRB SEBBRBRBRBEBRBBRBBASEEBE 
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System Function Summary 


Func Function Name 


O System Reset 
Console Input 
Console Output 
Reader Input 

Punch Output 

List Output 

Direct Console I/O 
Get |/O Byte 

Set I/O Byte 

Print String 

10 Read Console Buffer 
11 Get Console Status 
12 Return Version Number 
1S Reset Disk System 
14 Select Disk 

15 Open File 

16 Close File 

17 Search for First 

18 Search for Next 

19 Delete File 

20 Read Sequential 

21 Write Sequential 

ce Make File 

20 Rename File 

24 Return Login Vector 
25 Return Current Disk 
26 Set DMA Address 
Zt Get Addr(Alloc) 

28 Write Protect Disk 
29 Get R/O Vector 

30 Set File Attributes 
ol Get Addr (disk parms) 
oe Set/Get User Code 
30 Read Random 

34 Write Random 

55 Compute File Size 
36 Set Random Record 


*Note the A=L, and B=H upon return 


OONDAFRWN — 


Input 
Parameters 


none 

none 
E=char 
none 
E=char 
E=char 
see def 
none 
E=IOBYTE 
DE=.Buffer 
DE=.Buffer 
none 
none 
none 
E=Disk Number 
DE=.FCB 
DE=.FCB 
DE=.FCB 
none 
DE=.FCB 
DE=.FCB 
DE=.FCB 
DE=.FCB 
DE=.FCB 
none 
none 
DE=.DMA 
none 
none 
none 
DE=.FCB 
none 

see def 
DE=.FCB 
DE=.FCB 
DE=.FCB 
DE=.FCB 


Output 
Results 


none 
A=char 
none 
A=char 
none 

none 

see def 
A=IOBYTE 
none 

none 

see def 
A=00/FF 
HL=Version* 
see def 

see def 
A=Dir Code 
A=Dir Code 
A=Dir Code 
A=Dir Code 
A=Dir Code 
A=Err Code 
A=Err Code 
A=Dir Code 
A=Dir Code 
HL=Login Vect* 
A=Cur Disk# 
none 
HL=.Alloc 
see def 
HL=R/O Vect* 
see def 
HL=.DPB 
see def 
A=Err Code 
A=Err Code 
‘O. Ti,%2 

fO, ¥1,'2 
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94 
95 
95 
99 
100 
102 
103 
107 
107 
108 
109 
110 
111 


Introduction to ED 

ED Operation 

Text Transfer Functions 
Memory Buffer Organization 
Memory Buffer Operation 
Command Strings 

Text Search and Alteration 
Source Libraries 

Repetitive Command Execution 
ED Error Conditions 

Summary of Control Characters 
Summary of ED Commands 

ED Text Editing Commands 
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3 
CP/M Editor 


Introduction to ED 


ED is the context editor for CP/M, and is used to create and alter 
CP/M source files. ED is initiated in CP/M by typing 


<filename> 
ED 


<filename> - <filetype> 


In general, ED reads segments of the source file given by 
<filename> or <filename> - <filetype> into central memory, where 
the file is manipulated by the operator, and subsequently written 
back to disk after alterations. If the source file does not exist before 
editing, it is created by ED and initialized to empty. The overall 
operation of ED is shown in Figure 1. 


BPEREBEESBBEESBEHEEREEBEREEEEHEEBEEEREBEE EE E 
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ED Operation 


ED operates upon the source file, denoted in Figure 1 by x.y, 

and passes all text through a memory buffer where the text can be 
viewed or altered (the number of lines which can be maintained 

in the memory buffer varies with the line length, but has a total 
capacity of about 6000 characters in a 16K CP/M system). Text 
material which has been edited is written onto a temporary work 
file under command of the operator. Upon termination of the 

edit, the memory buffer is written to the temporary file, followed by 
any remaining (unread) text in the source file. The name of the 
original file is changed from x.y to x.BAK so that the most recent 
previously edited source file can be reclaimed if necessary (see 
the CP/M commands ERASE and RENAME). The temporary file Is 
changed from x.$$$ to x.y which becomes the resulting edited 
file. 


The memory buffer is logically between the source file and working 
file as shown in Figure 2. 


Text Transfer Functions 


Given that n is an integer value in the range O through 65535, the 
following ED commands transfer lines of text from the source file 

through the memory buffer to the temporary (and eventually final) 
file: 
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Figure 1. Overall ED Operation 


Source 
Libraries 


Temporary 
File 


X.$$$ 


' after edit 
1(E) 
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Note 


The ED program accepts both lower and upper case 

ASCII characters as input from the console. Single letter 
commands can be typed in either case. The U command 
can be issued to cause ED to translate lower case 
alphabetics to upper case as characters are filled to 

the memory buffer from the console. Characters are echoed 
as typed without translation, however. The —U command 
causes ED to revert to “no translation” mode. ED starts 

with an assumed —U in effect. 


Figure 2. Memory Buffer Organization 


Source File Memory Buffer Temporary File 


text 


free 
memory 
space 


7TS3SBSBaeananauenauseauunaanaauaag 


98 CP/M Reference Manual 


Figure 3. Logical Organization of Memory Buffer 


first line 


Current 
line CL 


last 


line 


nA<cr>* 


nW<cr> 


=—cCr 


al? ee 


Memory Buffer 


<or>= i> 


= Cr-<lf> 


or >< lf> 


Append the next n unprocessed source 
lines from the source file at SP to the end of 
the memory buffer at MP. Increment SP and 
MP by n. 


Write the first n lines of the memory buffer 
to the temporary file free space. Shift the 
remaining lines n + 1 through MP to the top 
of the memory buffer. Increment TP by n. 


End the edit. Copy all buffered text to 
temporary file, and copy all unprocessed 
source lines to the temporary file. Rename 
files as described previously. 


Move to head of new file by performing 
automatic E command. Temporary file 
becomes the new source file, the memory 
buffer is emptied, and a new temporary file 
is created (equivalent to issuing an E 
command, followed by a reinvocation of ED 
using x.y as the file to edit). 


*<er> represents the carriage-return key 


BPEREEEBESBESEEBEE SE & 


BHREEEBEESBESEE SE & 


su83 5888 ad 


oe om ee oe 


J 


d 


SHRERBaE B 


aa 
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O=cr= Return to original file. The memory buffer 
is emptied, the temporary file is deleted, 
and the SP is returned to position 1 of the 
source file. The effects of the previous 
editing commands are thus nullified. 


O-cr= Quit edit with no file alterations, return 
to CP/M. 


There are a number of special cases to consider. If the integer n is 
omitted in any ED command where an integer is allowed, then 1 

is assumed. Thus, the commands A and W append one line and 
write 1 line, respectively. In addition, if a pound sign (#) is given 

in the place of n, then the integer 65535 is assumed (the largest 
value for n which is allowed). Since most reasonably sized 

source files can be contained entirely in the memory buffer, the 
command #A is often issued at the beginning of the edit to read 
the entire source file to memory. Similarly, the command #W writes 
the entire buffer to the temporary file. Two special forms of the A 
and W commands are provided as a convenience. The command 
OA fills the current memory buffer to at least half-full, while OW 
writes lines until the buffer is at least half empty. It should also be 
noted that an error is issued if the memory buffer size is exceeded. 
The operator may then enter any command (such as W) which does 
not increase memory requirements. The remainder of any partial 
line read during the overflow will be brought into memory on the 
next successful append. 


Memory Buffer Organization 


The memory buffer can be considered a sequence of source lines 
brought in with the A command from a source file. The memory 
buffer has an associated (imaginary) character pointer (CP) which 
moves throughout the memory buffer under command of the 
operator. The memory buffer appears logically as shown in Figure 3 
where the dashes represent characters of the source line of 
indefinite length, terminated by carriage return (<cr>) and line feed 
(<1f>) characters, and 4 represents the imaginary character 
pointer. Note that the CP is always located ahead of the first 
character of the first line, behind the last character of the last 
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line, or between two characters. The current line CL is the source 
line which contains the CP. 


Memory Buffer Operation 


Upon initiation of ED, the memory buffer is empty (i.e., CP is both 
ahead and behind the first and last character). The operator may 
either append lines (A command) from the source file, or enter the 
lines directly from the console with the insert command 


cr 


ED then accepts any number of input lines, where each line 
terminates with a <cr> (the <If> is supplied automatically), until a 
control-z (denoted by 72) is typed by the operator. The CP is 
positioned after the last character entered. The sequence 


—cr> 

NOW IS THE<cr> 
TIME FOR<cr> 

ALL GOOD MEN<cr> 
TZ 


leaves the memory buffer as shown below 


NOW IS THE<cr> <lf> 
TIME FOR<cr> <If> 
ALL GOOD MEN«<cr> <If>4 


Various commands can then be issued which manipulate the CP or 
display source text in the vicinity of the CP. The commands 

shown below with a preceding n indicate that an optional unsigned 
value can be specified. When preceded by +, the command can 
be unsigned, or have an optional preceding plus or minus sign. As 
before, the pound sign (#) is replaced by 65535. If an integer nis 
optional, but not supplied, then n=1 is assumed. Finally, if a plus 
sign is optional, but none is specified, then + is assumed. 


BEREBEBEEBEESBESE SEs 


a 


BREESE EB E 


a 


5suueseuannaaa 


ZB & 
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+B <cr> 


=—nG-cr 


hh cr 


=nK=cr> 


=nL=cr> 


+ hnl<cr=> 


fcr 
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move CP to beginning of memory buffer if 
+, and to bottom if —. 


move CP by =n characters (toward front of 
buffer if +), counting the <cr > <If> as two 
distinct characters. 


delete n characters ahead of CP if plus and 
behind CP if minus. 


kill (i.e., remove) +n lines of source text 
using CP as the current reference. If CP is 
not at the beginning of the current line when 
K is issued, then the characters before 

CP remain if + is specified, while the 
characters after CP remain if — is given in 
the command. 


if n =O, move CP to the beginning of 

the current line (if it is not already there). 
If n#O, first move the CP to the beginning 
of the current line, and then move it to the 
beginning of the line which is n lines down 
(if +) or up (if —). The CP will stop at the 
top or bottom of the memory buffer if too 
large a value is specified. 


If n = O then type the contents of the 
current line up to CP. If n = 1 then type the 
contents of the current line from CP to the 
end of the line. If n>1 then type the 
current line along with n—1 lines which 
follow, if + is specified. Similarly, if n>1 and 
— is given, type the previous n lines, up to 
the CP. The Break key can be depressed to 
abort long type-outs. 


equivalent to =nLT, which moves up or down 
and types a single line. 


102 CP/M Reference Manual 


Command Strings 


Any number of commands can be typed contiguously (up to the 
capacity of the CP/M console buffer), and are executed only 
after the <cr> is typed. Thus, the operator may use the CP/M 
console command functions to manipulate the input command. 


Rubout remove the last character 
Control-X delete the entire line 
Control-C re-initialize the CP/M System 
Control-E 


return carriage for long lines without trans- 


mitting buffer (max 128 chars) 


Suppose the memory buffer contains the characters shown in the 
previous section, with the CP following the last character of the 
buffer. The command strings shown below produce the results 
shown to the right. 


Command 
String 


B2T<cr> 


5COl<cr> 


PACA Ee oe 


=—_#K=<cr> 


Effect 


move to beginning of 
buffer and type 2 lines: 
“NOW IS THE 

TIME FOR” 


move CP 5 characters 
and type the beginning 
of the line “NOW |” 


move two lines down 
and type previous line 
“TIME FOR” 


move up one line, 
delete 65535 lines 
which follow 


Resulting Memory Buffer 


4, NOW IS THE<cr> <lf> 
TIME FOR<cr> <If> 
ALL GOOD MEN<cr> <lIf> 


NOW | 4,S THE<cr> <If> 


NOW IS THE<cr> <lIf> 
TIME FOR<cr> <lf> 
4, ALL GOOD MEN«<cr> <If> 


NOW IS THE<cr> <If>4, 


BPHREREBSEEBEEESBEEBEHREHEESE SE 
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Command 
| String Effect Resulting Memory Buffer 
| I<cr> insert two lines NOW IS THE<cr> <lIf> 
| TIME TO<cr> of text TIME TO<cr> <l|f> 
| INSERT<cr> INSERT<cr> <If>4, 
TZ 


—2L#T<cr>  moveuptwolines,and NOWIS THEx<cr> <lf-4 
type 65535 lines ahead TIME TO<cr><lf> 


of CP “NOW IS THE” INSERT<cr> <If> 

| <or move down one line NOW IS THE<cr> <lf> 
and type one line TIME TO<cr> <If>4, 

| “INSERT” INSERT<cr> <If> 


Text Search and Alteration 


ED also has a command which locates strings within the memory 
buffer. The command takes the form 


Nr Cs... 


<cr> 
4 


where c, through c, represent the characters to match 

followed by either a <cr> or control-z.* ED starts at the current 
position of CP and attempts to match all k characters. The match 

is attempted n times, and if successful, the CP is moved directly 
after the character c,. If the n matches are not successful, the 

CP is not moved from its initial position. Search strings can include 
FI (control-l), which is replaced by the pair of symbols <cr> <If>. 


*The control-z is used if additional commands will be typed following the *z. 


BREREEHESBEEBESEBEHEEHEEHEEBREHEHEHEEEHREEHEEBE SE GS 
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The following commands illustrate the use of the F command: 


Command 

String Effect Resulting Memory Buffer 

B#T<cr> move to beginning 4, NOW IS THE<cr> <lf> 
and type entire TIME FOR<cr> <lIf> 
buffer ALL GOOD MEN<cr> <If> 

Fo ler find the end of NOW IS TAHE<cr> <lf> 
the string “S T” 

FITZOTT find the next “Il” and NOW IS THE<cr> <lIf> 
type to the CP then TIAME FOR<cr> <lf> 


type the remainder of ALL GOOD MEN<cr> <I|f> 
the current line: 
“TIME FOR” 


An abbreviated form of the insert command is also allowed, 
which is often used in conjunction with the F command to make 
simple textural changes. The form is: 


1C305.4,0,12 “Or 
0 e..3. Cor 


where c, through c, are characters to insert. If the insertion 

string is terminated by a Tz, the characters c, through 

Cc, are inserted directly following the CP, and the CP is moved 
directly after character c,. The action is the same if the command 
is followed by a<cr> except that a <cr> <If> is automatically 
inserted into the text following character c,. Consider the following 
command sequences as examples of the F and | commands: 


BPHREREEEEBEEHREHEEHREEHEEBEEHEHEEHEEBEEHEEHEEHEEHEEBEEEE SES 
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"SSBB BUBBRBBKBBeewewesaeaeasuaa 


Command 
String Effect Resulting Memory Buffer 
BITHIs ls Tz=cr> 
Insert “THIS IS” THISIS4NOW THE<cr><lf> 
at the beginning TIME FOR<cr> <lf> 
of the text ALL GOOD MEN<cr> <lf> 
FTIMETZz—4DIPLACE7Tz<cr> THIS IS NOW THE<cr> <If> 


find “TIME” and delete PLACE4&FOR<cr> <lf> 
it; then insert “PLACE” ALL GOOD MEN<cr> <lf> 


3FOTz—3D5DICHANGEST<cr> THIS IS NOW THE<cr> <If> 
find third occurrence of PLACE FOR<cr> <lf> 
“OQ” (i.e., the second “O” ALL CHANGES&<cr> <If> 
in GOOD), delete pre- 
vious 3 characters; then 
insert “CHANGES” 


-8CISOURCE<cr> 
move back 8 characters THIS IS NOW THE<cr> <lf> 


and insert the line PLACE FOR<cr> <lf> 
"SOURCE<cre> =i" ALL. SOURGE<cr> <li> 
4 CHANGES<cr> <If> 


ED also provides a single command which combines the F and | 
commands to perform simple string substitutions. The command 
takes the form 


<cr> 
VS Ci65 na | 20 es, | rz | 


and has exactly the same effect as applying the command string 


Fc.c>...¢,tZ—kDld,d,... dp, ! pos | 
Zz 

a total of n times. That is, ED searches the memory buffer starting 

at the current position of CP and successively substitutes the 

second string for the first string until the end of buffer, or until 

the substitution has been performed n times. 
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As a convenience, a command similar to F is provided by ED which 


automatically appends and writes lines as the search proceeds. 
The form is 


I Gao «24, 


<cr> 
TZ 


which searches the entire source file for the nth occurrence of the 
string C,C....C, (recall that F fails if the string cannot be found in 
the current buffer). The operation of the N command is precisely 


the same as F except In the case that the string cannot be found 


within the current memory buffer. In this case, the entire memory 
contents is written (i.e., an automatic #W is issued). Input lines are 


then read until the buffer is at least half full, or the entire source 
file is exhausted. The search continues in this manner until the 
string has been found n times, or until the source file has been 
completely transferred to the temporary file. 


A final line editing function, called the juxtaposition command takes 


the form 


id COsuccG 12 O10s.csO, 2 e108} | 


with the following action applied n times to the memory buffer: 
search from the current CP for the next occurrence of the string 
C,C....C,. If found, insert the string d,,d....d,,, and move CP to 
follow d,,. Then delete all characters following CP up to (but not 
including) the string e,,@5,...€,, leaving CP directly after d,,. If 
€;,o,...@, cannot be found, then no deletion is made. If the 
current line is 


4 NOW IS THE TIME<cr> <lf> 
Then the command 

JW TZWHATTzT1<cr> 
results in 


NOW WHAT &x<cr> <If> 
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(Recall that Tl represents the pair <cr> <If> in search and 
Substitution strings.) 


It should be noted that the number of characters allowed by 
ED in the F,S,N, and J commands is limited to 100 symbols. 


Source Libraries 


ED also allows the inclusion of source libraries during the editing 
process with the R command. The form of this command Is 

Fi ijlsixtp  Z or 

AitG..1cr> 
where f,f. . . f, is the name of a source file on the disk with an 
assumed filetype of ‘LIB:!ED reads the specified file, and places 


the characters into the memory buffer after CP, in a manner 
similar to the | command. Thus, if the command 


RMACRO<cr> 
is issued by the operator, ED reads from the file MACRO.LIB 


until the end-of-file, and automatically inserts the characters into 
the memory buffer. 


Repetitive Command Execution 


The macro command M allows the ED user to group ED commands 
together for repeated evaluation. The M command takes the form: 


<or> 
gyre 


AM C305. ws Cy | 


where c,c....C, represent a string of ED commands, not including 
another M command. ED executes the command string n times 

if n>1. If n=O or 1, the command string is executed repetitively until 
an error condition is encountered (e.g., the end of the memory 
buffer is reached with an F command). 
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As an example, the following macro changes all occurrences of 
GAMMA to DELTA within the current buffer, and types each line 
which is changed: 

MFGAMMATz—5DIDELTATZzOTT<cr> 


or equivalently 


MSGAMMATZDELTATZzOTT<cr> 


ED Error Conditions 


On error conditions, ED prints the last character read before the 
error, along with an error indicator: 


unrecognized command 


> memory buffer full (use one of the 
commands D, K, N, S, or W to remove 
characters), F, N, or S strings too long. 


= cannot apply command the number of times 
specified (e.g., in F command) 


O cannot open LIB file in R command 


Cyclic redundancy check (CRC) information is written with each 
output record under CP/M in order to detect errors on subsequent 
read operations. If a CRC error is detected, CP/M will type 


PERM ERR DISK d 


where d is the currently selected drive (A, B,...). The operator 
can choose to ignore the error by typing any character at the 
console (in this case, the memory buffer data should be examined 
to see If it was incorrectly read), or the user can reset the 

system and reclaim the backup file, if it exists. The file can 

be reclaimed by first typing the contents of the BAK file to 

ensure that it contains the proper information. 


TYPE X.BAK<cr> 
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| 
| - where x is the file being edited. Then remove the primary file: 
| ERA x.y<cr> 
| a 
| and rename the BAK file: 
| 
REN x.y=x.BAK<cr> 
- 
| - The file can then be re-edited, starting with the previous system. 
-™ = Summary of Control Characters 
| | | 
| The following table summarizes the Control characters and 
- commands available in ED: 
= Control Character Function 
~ Te system reboot 
= Te ohysical <cr><lf>(not actually 
| entered in command) 
~ TI logical tab (cols 1, 8, 15,...) 
- gi logical <cr><If> in search 
| a and substitute strings 
| - TX line delete 
| TZ string terminator 
| & rubout character delete 
break discontinue command 
| (e.g., stop typing) 
| & 
- 
2 
ss 
i 
| 
| a 
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Command 


nA 


=n=Cr- 


Summary of ED Commands 


Function 

append lines 

begin bottom of buffer 
move character positions 
delete characters 


end edit and close files 
(normal end) 


find string 

end edit, close and reopen files 
insert characters 

place strings in juxtaposition 
kill lines 

move down/up lines 

macro definition 


find next occurrence with 
autoscan 


return to original file 
move and print pages 
quit with no file changes 
read library file 
substitute strings 

type lines 


translate lower to upper case 
if U, no translation if —U 


write lines 
sleep 


move and type (+nLT) 


EREEE & 


a 
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ED Text Editing Commands 


The ED context editor contains a number of commands which 
enhance its usefulness in text editing. The improvements are found 
in the addition of line numbers, free space interrogation, and 
improved error reporting. 


The context editor issued with CP/M produces absolute line number 
orefixes when the “V” (Verify Line Numbers) command is issued. 
Following the V command, the line number is displayed ahead of 
each line in the format: 


nNnNNAN: 


where nnnnn is an absolute line number in the range 1 to 65535. 
lf the memory buffer is empty, or if the current line is at the end 
of the memory buffer, then nnnnn appears as 5 blanks. 


The user may reference an absolute line number by preceding any 
command by a number followed by a colon, in the same format 

as the line number display. In this case, the ED program moves 
the current line reference to the absolute line number, if the 

line exists in the current memory buffer. Thus the command 


345:T 


is interpreted as “move to absolute line 345, and type the line.” 
Note that absolute line numbers are produced only during the 
editing process, and are not recorded with the file. In particular, 
the line numbers will change following a deleted or expanded 
section of text. 


The user may also reference an absolute line number as a 
| backward or forward distance from the current line by preceding 
| the absolute line number by acolon. Thus, the command 


PHREHRESBEBEHREBEHEHEEHEERBEEEEH SE & 


‘400T 


is interpreted as “type from the current line number through the 


oe 
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line whose absolute number is 400.” Combining the two line 
reference forms, the command 


345::400T 


for example, is interpreted as “move to absolute line 345, then 
type through absolute line 400.” Note that absolute line 
references of this sort can precede any of the standard ED 
commands. 


A special case of the V command, “OV,” prints the memory 
buffer statistics in the form: 


free/total 


where ‘free’ is the number of free bytes in the memory buffer 
(in decimal), and “total” is the size of the memory buffer. 


ED also includes a ‘block move’ facility implemented through 
the “X” (Xfer) command. The form 


nx 


transfers the next n lines from the current line to a temporary 
file called 


X$$$$$$$.LIB 


which is active only during the editing process. In general, 

the user can reposition the current line reference to any portion 
of the source file and transfer lines to the temporary file. The 
transferred lines accumulate one after another in this file, and can 
be retrieved by simply typing: 


R 


which is the trivial case of the library read command. In this 

case, the entire transferred set of lines is read into the memory 
buffer. Note that the X command does not remove the transferred 
lines from the memory buffer, although a K command can be used 
directly after the X, and the R command does not empty the 
transferred line file. That is, given that a set of lines has been 
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transferred with the X command, they can be re-read any number 
of times back into the source file. The command 


OX 
is provided, however, to empty the transferred line file. 


Note that upon normal completion of the ED program through 

Q or E, the temporary LIB file is removed. If ED is aborted through 
Control-C, the LIB file will exist if lines have been transferred, 

but will generally be empty (a subsequent ED invocation will erase 
the temporary file). 


Due to common typographical errors, ED requires several 
potentially disastrous commands to be typed as single letters, 
rather than in composite commands. The commands 

E (end), H (head), O (original), Q (quit) 
must be typed as single letter commands. 


ED also prints error messages in the form 


BREAK “x” AT c 


where x is the error character, and c is the command where the 
error occurred. 
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4 
CP/M Assembler 


Introduction 


The CP/M assembler reads assembly language source files from 
the diskette, and produces 8080 machine language in Intel hex 
format. The CP/M assembler is initiated by typing 


ASM filename 
or 
ASM filename.parms 


In both cases, the assembler assumes there is a file on the diskette 
with the name 


filename.ASM 
which contains an 8080 assembly language source file. The first 
and second forms shown above differ only in that the second form 
allows parameters to be passed to the assembler to control 
source file access and hex and print file destinations. 
In either case, the CP/M assembler loads, and prints the message 


CP/M ASSEMBLER VER n.n 


where n.n is the current version number. In the case of the first 
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command, the assembler reads the source file with assumed file 
type ‘ASM’ and creates two output files. 


filename.HEX 
and 
filename.PRN 


The “HEX” file contains the machine code corresponding to the 
original program in Intel hex format, and the “PRN” file contains 
an annotated listing showing generated machine code, error flags, 
and source lines. If errors occur during translation, they will be 
listed in the PRN file as well as at the console. 


Se B28 2B 


The second command form can be used to redirect input and 
output files from their defaults. In this case, the “parms” portion 

of the command is a three letter group which specifies the origin of 
the source file, the destination of the hex file, and the destination 

of the print file. The form is | 


filename.p1p2p3 
where p1, p2, and p3 are single letters 


OT A,B acy ¥ designates the disk name which contains 
the source file 


b2: FB, uy ¥ designates the disk name which will 
receive the hex file 
Z skips the generation of the hex file 


OS! ALB, in; Y designates the disk name which will 
receive the print file 
X places the listing at the console 
Zz skips generation of the print file 


Thus, the command 

ASM X.AAA 
indicates that the source file (X.ASM) is to be taken from disk A, 
and that the hex (X.HEX) and the print (X.PRN) files are to be 


created also on disk A. This form of the command is implied if 
the assembler is run from disk A. That is, given that the operator is 


7[BBSSBS8BEBRBaensunaaan 
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currently addressing disk A, the above command is equivalent to 
ASM X 

The command 
ASM X.ABX 


indicates that the source file is to be taken from disk A, the hex 
file is placed on disk B, and the listing file is to be sent to the 
console. The command 


ASM X.BZZ 


takes the source file from disk B, and skips the generation of the 
hex and print files. (This command is useful for fast execution of 
the assembler to check program syntax.) 


The source program format is compatible with both the Intel 

8080 assembler (macros are not currently implemented in the 
CP/M assembler, however) as well as the Processor Technology 
Software Package #1 assembler. That is, the CP/M assembler 
accepts source programs written in either format. There are 

certain extensions in the CP/M assembler which make it somewhat 
easier to use. These extensions are described below. 


Program Format 


An assembly language program acceptable as input to the 
assembler consists of a sequence of statements of the form 


line # label operation Operand ‘comment 


where any or all of the fields may be present in a particular 
instance. Each assembly language statement is terminated with 

a carriage return and line feed (the line feed is inserted automatically 
by the ED program), o with the character’! which is treated as 

an end-of-line by the assembler (thus, multiple assembly language 
statements can be written on the same physical line if separated 

by exclamation symbols). 
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The line# is an optional decimal integer value representing the 
source program line number, which is allowed on any source line 
to maintain compatibility with the Processor Technology format. In 
general, these line numbers will be inserted if a line-oriented 
editor is used to construct the original program, and thus ASM 
ignores this field if present. 


The label field takes the form 


identifier 
or 
identifier: 


and is optional, except where noted in particular statement 

types. The identifier is a sequence of alphanumeric characters 
(alohabetics and numbers), where the first character is alphabetic. 
Identifiers can be freely used by the programmer to label elements 
such as program steps and assembler directives, but cannot 
exceed 16 characters in length. All characters are significant in an 
identifier, except for the embedded dollar symbol ($) which can 
be used to improve readability of the name. Further, all lower case 
alphabetics are treated as if they were upper case. Note that the 
“:” following the identifier in a label is optional. Thus, the 
following are all valid instances of labels 


x xX y longsname 
x: vy xT: longer$named $data: 
X1Y2 ) a X234$5678$9012$3456: 


The operation field contains either an assembler directive, or 
oseudo operation, or an 8080 machine operation code. The 
oseudo operations and machine operation codes are described 
below. 


The operand field of the statement, in general, contains an 
expression formed out of constants and labels, along with arithmetic 
and logical operations on these elements. Again, the complete 
details of properly formed expressions are given below. 


The comment field contains arbitrary characters following the °;” 
symbol until the next real or logical end-of-line. These characters 
are read, listed, and otherwise ignored by the assembler. In order 
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to maintain compatibility with the Processor Technology assembler, 
the CP/M assembler also treats statements which begin with a 
“in column one as comment statements, which are listed and 
ignored in the assembly process. Note that the Processor 
Technology assembler has the side effect in its operation of ignoring 
the characters after the operand field has been scanned. This 
Causes an ambiguous situation when attempting to be compatible 
with Intel's language, since arbitrary expressions are allowed in 
this case. Hence, programs which use this side effect to introduce 
comments, must be edited to place a ‘’;” before these fields in 
order to assemble correctly. 


The assembly language program is formulated as a sequence of 
statements of the above form, terminated optionally by an END 
statement. All statements following the END are ignored by the 
assembler. 


Forming the Operand 


In order to completely describe the operation codes and pseudo 
operations, it is necessary to first present the form of the operand 
field, since it is used in nearly all statements. Expressions in the 
operand field consist of simple operands (labels, constants, and 
reserved words), combined in properly formed subexpressions 

by arithmetic and logical operators. The expression computation is 
carried out by the assembler as the assembly proceeds. Each 
expression must produce a 16-bit value during the assembly. 
Further, the number of significant digits in the result must not 
exceed the intended use. That is, if an expression is to be used ina 
byte move immediate instruction, then the most significant 8 bits 
of the expression must be zero. The restrictions on the expression 
significance are given with the individual instructions. 


Labels 


As discussed above, a label is an identifier which occurs on a 
particular statement. In general, the label is given a value determined 
by the type of statement which it precedes. If the label occurs ona 
statement which generates machine code or reserves memory 
space (e.g., a MOV instruction, or a DS pseudo operation), then the 
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label is given the value of the program address which it labels. If 
the label precedes an EQU or SET, then the label is given the value 
which results from evaluating the operand field. Except for the 
SET statement, an identifier can label only one statement. 


When a label appears in the operand field, its value is substituted 
by the assembler. This value can then be combined with other 
operands and operators to form the operand field for a particular 
instruction. 


Numeric Constants 


A numeric constant is a 16-bit value in one of several bases. The 
base, called the radix of the constant, is denoted by a trailing radix 
indicator. The radix indicators are 


binary constant (base 2) 

octal constant (base 8) 

octal constant (base 8) 

decimal constant (base 10) 
hexadecimal constant (base 16) 


rTODO0OW 


Q is an alternate radix indicator for octal numbers since the letter O 
is easily confused with the digit O. Any numeric constant which 
does not terminate with a radix indicator is assumed to be a 
decimal constant. 


A constant is thus composed as a sequence of digits, followed by 
an optional radix indicator, where the digits are in the appropriate 
range for the radix. That is binary constants must be composed 

of O and 1 digits, octal constants can contain digits in the range 
O—7, while decimal constants contain decimal digits. Hexadecimal 
constants contain decimal digits as well as hexadecimal digits A 
(10D), B (11D), C (12D), D (13D), E (14D), and F (15D). Note that 
the leading digit of a hexadecimal constant must be a decimal digit 
in order to avoid confusing a hexadecimal constant with an 
identifier (a leading O will always suffice). A constant composed in 
this manner must evaluate to a binary number which can be 
contained within a 16-bit counter, otherwise it is truncated on the 
right by the assembler. Similar to identifiers, imbedded “$" are 
allowed within constants to improve their readability. Finally, the 
radix indicator is translated to upper case if a lower case letter is 
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encountered. The following are all valid instances of numeric 
constants 


1234 1234D 1100B 1111$0000$1111$0000B 
1234H OFFEH 33770 33$77$22Q 
33770 Ofe3Sh 1234d Offffh 


Reserved Words 


There are several reserved character sequences which have 
predefined meanings in the operand field of a statement. The 
names of 8080 registers are given below, which, when encountered, 
produce the value shown to the right. 


A 7 
B 0 
C 1 
D 2 
= 3 
H 4 
L 5 
M 6 
or 6 
PSW 6 


(Again, lower case names have the same values as their upper case 
equivalents.) Machine instructions can also be used in the 
operand field, and evaluate to their internal codes. In the case of 
instructions which require operands, where the specific operand 
becomes a part of the binary bit pattern of the instruction (e.g., 
MOV A,B), the value of the instruction (in this case MOV) Is the 

bit pattern of the instruction with zeroes in the optional fields (e.g., 
MOV produces 40H). 


When the symbol “$” occurs in the operand field (not imbedded 
within identifiers and numeric constants) its value becomes the 
address of the text instruction to generate, not including the 
instruction contained within the current logical line. 
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String Constants 


String constants represent sequences of ASCII characters, and are 
represented by enclosing the characters within apostrophe 
symbols ('). All strings must be fully contained within the current 
physical line (thus allowing ‘!” symbols within strings), and must 
not exceed 64 characters in length. The apostrophe character itself 
can be included within a string by representing it as a double 
apostrophe (the keystrokes’), which becomes a single apostrophe 
when read by the assembler. In most cases, the string length is 
restricted to either one or two characters (the DB pseudo operation 
is an exception), in which case the string becomes an 8 or 16 bit 
value, respectively. Two character strings become a 16-bit constant, 
with the second character as the low order byte, and the first 
character as the high order byte. 


The value of a character is its corresponding ASCII code. There is 
no case translation within strings, and thus both upper and lower 
case characters can be represented. Note however, that only 
graphic (printing) ASCII characters are allowed within strings. 
Valid strings are 


A AB’ ‘ab’ Cc 


99999 YD 


‘She said “Hello” to me.’ 
‘| said “Hello” to her. 


Arithmetic and Logical Operators 


The operands described above can be combined in normal algebraic 
notation using any combination of properly formed operands, 
operators, and parenthesized expressions. 


The operators recognized in the operand field are 


ath unsigned arithmetic sum of a and b 
a= unsigned arithmetic difference between 
aandb 


CP/M Reference Manual 


+b unary plus (produces b) 

—b unary minus (identical to O — b) 

axb unsigned magnitude multiplication of a and b 

a/b unsigned magnitude division of a by b 

a MOD b remainder aftera/b 

NOT b logical inverse of b (all O’s become 1's, 1's 
become 0’s), where b is considered a 
16-bit value 

a AND b bit-by-bit logical and of a and b 

aORb bit-by-bit logical or of aand b 

a XOR b bit-by-bit logical exclusive or of a and b 

aSHLb the value which results from shifting a to the 
left by an amount b, with zero fill 

aSHRb the value which results from shifting a to 


the right by an amount b, with zero fill 


In each case, a and b represent simple operands (labels, numeric 
constants, reserved words, and one or two character strings), or 
fully enclosed parenthesized subexpressions such as 


10+20 10h+37Q tio (L2+4)SHRS 
(‘a and 5fh) + ‘0’ ((B’+B) OR (PSW+M) 
(1+(2+c)) shr (A—(B+1)) 


Note that all computations are performed at assembly time as 
16-bit unsigned operations. Thus, —1 is computed as O—1 which 
results in the value Offffh (i.e., all 1’s). The resulting expression 
must fit the operation code in which it is used. If, for example, the 
expression is used in a ADI (add immediate) instructions, then 
the high order eight bits of the expression must be zero. As a 
result, the operation “ADI—1” produces an error message (—1 
becomes Offffh which cannot be represented as an 8 bit value), 
while ‘ADI (—1) AND OFFH’” is accepted by the assembler since 
the “AND” operation zeroes the high order bits of the expression. 
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Precedence of Operators 


As aconvenience to the programmer, ASM assumes that operators 
have a relative precedence of application which allows the 
programmer to write expressions without nested levels of 
parentheses. The resulting expression has assumed parentheses 
which are defined by the relative precedence. The order of 
application of operators in unparenthesized expressions Is listed 
below. Operators listed first have highest precedence (they are 
applied first in an unparenthesized expression), while operators 
listed last have lowest precedence. Operators listed on the same 
line have equal precedence, and are applied from left to right as 
they are encountered in an expression 


« / MOD SHL SHR 
—+ 

NOT 

AND 

OR XOR 


Thus, the expressions shown to the left below are interpreted by 
the assembler as the fully parenthesized expressions shown to the 
right below 


ax*ore la *# OD) + 
at+tb*«c a+(b*c) 
aMODb«cSHLd ((a MOD b)*c) SHLd 


aORbANDNOTc+dSHLe aOR(bAND (NOT (c + (d SHL e)))) 
Balanced parenthesized subexpressions can always be used to 
override the assumed parentheses, and thus the last expression 


above could be rewritten to force application of operators in a 
different order as 


(a OR b) AND (NOT c) +d SHLe 
resulting in the assumed parentheses 
(a OR b) AND ((NOT c) + (d SHL e)) 
Note that an unparenthesized expression is well-formed only if 


the expression which results from inserting the assumed 
parentheses is well-formed. 
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Assembler Directives 


Assembler directives are used to set labels to specific values 
during the assembly, perform conditional assembly, define storage 
areas, and specify starting addresses in the program. Each assembler 
directive is denoted by a ‘pseudo operation” which appears in 

the operation field of the line. The acceptable pseudo operations 
are 


ORG set the program or data origin 
END end program, optional start address 
EQU numeric ‘equate’ 
SEP numeric ‘set’ 
IF begin conditional assembly 
ENDIF end of conditional assembly 
DB define data bytes 
DW define data words 
DS define data storage area 
The ORG Directive 


The ORG statement takes the form 
label ORG expression 


where ‘label’ is an optional program label, and expression is a 
16-bit expression, consisting of operands which are defined 
previous to the ORG statement. The assembler begins machine 
code generation at the location specified in the expression. 

There can be any number of ORG statements within a particular 
program, and there are no checks to ensure that the programmer 

is not defining overlapping memory areas. Note that most programs 
written for the CP/M system begin with an ORG statement of the 
form 


ORG 100H 


which causes machine code generation to begin at the base of the 
CP/M transient program area. If a label is specified in the ORG 
statement, then the label is given the value of the expression (this 
label can then be used in the operand field of other statements 

to represent this expression). 
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The END Directive 


The END statement is optional in an assembly language program, 
but if it is present it must be the last statement (all subsequent 
statements are ignored in the assembly). The two forms of the END 
directive are 


label END 
label END expression 


where the label is again optional. If the first form is used, the 
assembly process stops, and the default starting address of the 
program is taken as OOOO. Otherwise, the expression is evaluated, 
and becomes the program starting address (this starting address 
is included in the last record of the Intel formatted machine code 
“hex” file which results from the assembly). Thus, most CP/M 
assembly language programs end with the statement 


END 100H 


resulting in the default starting address of 100H (beginning of the 
transient program area). 


The EQU Directive 


The EQU (equate) statement is used to set up synonyms for 
particular numeric values. The form is 


label EQU expression 


where the label must be present, and must not label any other 
statement. The assembler evaluates the expression, and assigns 
this value to the identifier given in the label field. The identifier is 
usually a name which describes the value in a more human-oriented 
manner. Further, this name is used throughout the program to 
“oarameterize’ certain functions. Suppose for example, that data 
received from a Teletype appears on a particular input port, and 
data is sent to the Teletype through the next output port in 
sequence. 
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The series of equate statements could be used to define these 
ports for a particular hardware environment 


TTYBASE EQU 10H ‘BASE PORT NUMBER FOR TTYLe 


TTYIN EQU TTYBASE sTTY DATA IN 
TTYOUT EQU TTYBASE+1 ;TTY DATA OUT 


At a later point in the program, the statements which access the 
Teletype could appear as 


IN TTYIN “READ TTY DATA TO REG—A 

OUT 1PYOUT ‘WRITE DATA TO TTY FROM REG—A 
making the program more readable than if the absolute I/O ports 
had been used. Further, if the hardware environment is redefined 
to start the Teletype communications ports at 7FH instead of 10H, 
the first statement need only be changed to 
TTYBASE EQU 7FH ‘BASE PORT NUMBER FOR TTY 


and the program can be reassembled without changing any other 
statement. 


The SET Directive 
The SET statement is similar to the EQU, taking the form 
label SET expression 
except that the label can occur on other SET statements within 


the program. The expression is evaluated and becomes the current 
value associated with the label. Thus, the EQU statement defines 


EBREEREEERBSEESE & 
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BEREREEREEREEEEREEEEEEE EL 


i 


CP/M Assembler 129 


a label with a single value, while the SET statement defines a value 
which is valid from the current SET statement to the point where 
the label occurs on the next SET statement. The use of the SET is 
similar to the EQU statement, but is used most often in controlling 
conditional assembly. 


The IF and ENDIF Directives 


The IF and ENDIF statements define a range of assembly language 
statements which are to be included or excluded during the 
assembly process. The form is 


IF expression 
statement #1 
statement #2 


statement #n 
ENDIF 


Upon encountering the IF statement, the assembler evaluates 

the expression following the IF (all operands in the expression 
must be defined ahead of the IF statement). If the expression 
evaluates to a non-zero value, then statement #1 through statement 
+n are assembled; if the expression evaluates to zero, then the 
statements are listed but not assembled. Conditional assembly !s 
often used to write a single “generic” program which includes a 
number of possible run-time environments, with only a few specific 
portions of the program selected for any particular assembly. The 
following program segments for example, might be part of a program 
which communicates with either a Teletype or a CRT console 

(but not both) by selecting a particular value for TTY before the 
assembly begins. 
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TTYBASE 
CRTBASE 


CONIN 


CONOUT 


CONIN 
CONOUT 


In this case, 


TTY 


OUT 


OFFFFH 
NOT TRUE 


TRUE 

10H 

20H 

TY 
TTYBASE 
TTYBASE+1 
NOT TTY 
CRTIBASE 
CRIBASE+1 
CONIN 


CONOUT 


DEFINE VALUE OF TRUE 
DEFINE VALUE OF FALSE 


RUE IP TTY, FALSE IF CRT 


sBASE OF TTY I/O PORTS 
sBASE OF CRT I/O PORTS 
“ASSEMBLE RELATIVE TO 
TTYBASE 

;CONSOLE INPUT 
;CONSOLE OUTPUT 


SASSEMBLE RELATIVE TO 
CRIBASE 

;SCONSOLE INPUT 
;CONSOLE OUTPUT 


;-READ CONSOLE DATA 


WRITE CONSOLE DATA 


the program would assemble for an environment 
where a Teletype Is connected, based at port 10H. The statement 
defining TTY could be changed to 


EQU 


FALSE 


and, in this case, the program would assemble for a CRT based at 


port 20H. 
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The DB Directive 


The DB directive allows the programmer to define initialized 
storage areas in single precision (byte) format. The statement form 
IS 


label DB et1, e#2,..., etn 


where e#1 through e#n are either expressions which evaluate to 
8-bit values (the high order eight bits must be zero), or are ASCII 
strings of length no greater than 64 characters. There is no 
practical restriction on the number of expressions included on a 
single source line. The expressions are evaluated and placed 
sequentially into the machine code file following the last program 
address generated by the assembler. String characters are 
similarly placed into memory starting with the first character and 
ending with the last character. Strings of length greater than two 
characters cannot be used as operands in more complicated 
expressions (i.e., they must stand alone between the commas). 
Note that ASCII characters are always placed in memory with the 
parity bit reset (0). Further, recall that there is no translation from 
lower to upper case within strings. The optional label can be used 
to reference the data area throughout the remainder of the 
orogram. Examples of valid DB statements are 


data: DB 0:1,2,3,4,5 
DB. data and Offh,5,377Q,1+2+3+4 
signon: DB ‘please type your name’,cr,|f,O 


DB ‘AB’ SHR8, ‘C’, ‘DE’ AND 7FH 


The DW Directive 


The DW statement is similar to the DB statement except double 
precision (two byte) words of storage are initialized. The form Is 


label DW et1 d#2,..., ef#n 


where e#1 through e#n are expressions which evaluate to 16-bit 
results. Note that ASCII strings of length one or two characters are 
allowed, but strings longer than two characters disallowed. In all 
cases, the data storage is consistent with the 8080 processor: the 
least significant byte of the expression is stored first in memory, 
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followed by the most significant byte. Examples are 


doub: DW Offefh,doub+4,signon—$,255+255 
DW 4,5, ab,-CD.6shiG or 11b 


The DS Directive 


The DS statement is used to reserve an area of uninitialized 
memory, and takes the form 


label DS expression 
where the label is optional. The assembler begins subsequent 
code generation after the area reserved by the DS. Thus, the DS 
statement given above has exactly the same effect as the 
statement 
label: EQU $ ;LABEL VALUE IS CURRENT CODE LOCATION 
ORG $+ expression ;MOVE PAST RESERVED AREA 


Operation Codes 


Assembly language operation codes form the principal part of 
assembly language programs, and form the operation field of the 
instruction. In general, ASM accepts all the standard mnemonics 
for the Intel 8080 microcomputer, which are given in detail in the 
Intel manual 8080 Assembly Language Programming Manual. Labels 
are optional on each input line and, if included, take the value of 
the instruction address immediately before the instruction is issued. 
The individual operators are listed briefly in the following sections 
for completeness, although it is understood that the Intel manuals 
should be referenced for exact operator details. In each case, 


e3 represents a 3-bit value in the range of 0-7 which 
can be one of the predefined registers A, B, C, 
D, E, H, L, M, SP, or PSW. 


e8 represents an 8-bit value in the range 0-255 


e16 represents a 16-bit value in the range 0-65535 


BRE & 


BPHREHREEEEBEEBEEEBSEE & 


EBEEE & 


CP/M Assembler 133 


which can themselves be formed from an arbitrary combination 
of operands and operators. In some cases, the operands are 
restricted to particular values within the allowable range, such as 
the PUSH instruction. These cases will be noted as they are 
encountered. 


In the sections which follow, each operation code is listed in its 
most general form, along with a specific example, with a short 
explanation and special restrictions. 


Jumps, Calls and Returns 

The Jump, Call and Return instructions allow several different 
forms which test the condition flags set in the 8080 microcomputer 
CPU. The forms are 

JMB e16 JMP_ L1 Jump unconditionally to label 

JNZ e16 JMP L2 Jump on non zero condition to label 
JZ. e16 JMP  100H Jump on zero condition to label 
JNC e16 JNC L1+4 Jump no carry to label 


JC e16 JC L3 Jump on carry to label 

JPO e16 JPO- $+8 Jump on parity odd to label 
JPE e16 JPE L4 Jump on even parity to label 
JP e16 JP GAMMA Jump on positive result to label 
JM e16 JM al Jump on minus to label 

CALL e16 CALL $1 Call subroutine unconditionally 
CNZ e16 CNZ 82 Call subroutine if non zero flag 


CZ e16 CZ 100H Call subroutine on zero flag 
CNG e16 CNC $144 Call subroutine if no carry set 


CG e16 CC ete Call subroutine if carry set 
CPO e16 CPO $+8 Call subroutine if parity odd 
CPE e16 CPE S4 Call subroutine if parity even 


CP e16 CP GAMMA. Call subroutine if positive result 


PReHReHEBREHEHREEHEHRHEEBEBRHEHBREHREEHEHREEEEBEH SE GE 
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CM e16 CM b1$c2 


RST e3 


RET 
RNZ 
RZ 
RNC 
RC 
RPO 
Are 
RP 
RM 


RST O 


Call subroutine if minus flag 


Programmed “restart,” equivalent to 
CALL 8*e3, except one byte call 


Return from subroutine 
Return if non zero flag set 
Return if zero flag set 
Return if no carry 

Return if carry flag set 
Return if parity is odd 
Return if parity is even 
Return if positive result 


Return if minus flag is set 


Immediate Operand Instructions 


Several instructions are available which load single or double 
precision registers, or single precision memory cells, with constant 
values, along with instructions which perform immediate arithmetic 
or logical operations on the accumulator (register A). 


MVI e3,e8 


ADI e8 


ACI e8 


SUI e8 


SBI e8 


ANI e8 


MVI B,255 
ADI 1 

ACI OFFH 
sul L+3 


SBI LAND 11B 


ANI $AND7FH 


Move immediate data to 
register A,B, C, D, E, H, L, 
or M (memory) 


Add immediate operand to A 
without carry 


Add immediate operand to A 
with carry 


Subtract from A without 
borrow (carry) 


Subtract from A with borrow 
(carry) 


Logical “and” A with 
immediate data 
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XRI e8 XRI 1111$0000B “Exclusive or’ A with 
immediate data 
ORI e8 ORI LAND 1+1 Logical ‘or’ A with 


immediate data 


CPI e8 GP “a Compare A with immediate 
data (same as SUI except 
register A not changed) 


LXI e3,e16 LX| B,100H Load extended immediate to 
register pair (e3 must be 
equivalent to B, D, H, or SP) 


Increment and Decrement Instructions 


Instructions are provided in the 8080 repertoire for incrementing 
or decrementing single and double precision registers. The 
instructions are 


INR e3 INR E Single precision increment 
register (e3 produces one of 
A, BG, BD, Ay ky, WH 


DCR e3 DCR A Single precision decrement 
register (e3 produces one of 
A.B, C, Dy E, Ay by i} 


INX e3 INX SP Double precision increment 
register pair (e3 must be 
equivalent to B, D, H, or SP) 


DCX e3 DCX B Double precision decrement 
register pair (e3 must be 
equivalent to B, D, H, or SP) 


OUT  e8 OUT 255 Send data from register A 
to port e8 


"TREE EEEEEeEEeeeeeeeeeeeee 
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Data Movement Instructions 


Instructions which move data from memory to the CPU and from 
CPU to memory are given below 


MOV e3,e3 MOV A,B 


LDAX e3 


STAX e3 


LAL! <€16 


SHLD e16 


LDA e16 


STA e16 


POP e3 


PUSH e3 


OUT e8 


LDAX B 


STAX D 


LHLD L1 


SHLD L5+x 


LDA Gamma 


STA X3-5 


POP PSW 


PUSH B 


OUT 255 


Move data to leftmost 
element from rightmost 
element (e3 produces one of 
A, B.C, D, E, AL, or Mi). 
MOV M,M is disallowed 


Load register A from 
computed address (e3 must 
produce either B or D) 


Store register A to computed 
address (e3 must produce 
either B or D) 


Load HL direct from 
location e16 (double 
precision load to H and L) 


Store HL direct to location 
e16 (double precision store 
from H and L to memory) 


Load register A from 
address e16 


Store register A into memory 
at e16 


Load register pair from 
stack, set SP (e3 must 
produce one of B, D, H, 
or PSW) 


Store register pair into stack, 
set SP (e3 must produce 
one of B, D, H, or PSW) 


Load register A with data 
from port e8 


Send data from register A 
to port e8 
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PORL 
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Exchange data from top of 
stack with HL 


Fill program counter with 
data from HL 


Fill stack pointer with data 
from HL 


Exchange DE pair with HL 
pair 


Arithmetic Logic Unit Operations 


Instructions which act upon the single precision accumulator to 
perform arithmetic and logic operations are 


ADD 


ADC 


SUB 


SBB 


ANA 


XRA 


ORA 


CMP 


e3 


e3 


e3 


e3 


e3 


e3 


e3 


e3 


ADD 


ADC 


SUB 


SBB 


ANA 


XRA 


ORA 


CMP 


ry 


Add register given by e3 to 
accumulator without carry 
(e3 must produce one of 
A. B.C, BD, Ey Ay OF &) 


Add register to A with carry, 
e3 as above 


Subtract reg e3 from A 
without carry, e3 is defined 
as above 


Subtract register e3 from A 
with carry, e3 defined 
as above 


Logical “and” reg with A, e3 
as above 


“Exclusive or’ with A, e3 
as above 


Logical ‘or’ with A, e3 
defined as above 


Compare register with A, e3 
as above 
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DAA Decimal adjust register A 
based upon last arithmetic 
logic unit operation 


CMA Complement the bits in 
register A 

o1G Set the carry flag to 1 

CMC Complement the carry flag 

RLC Rotate bits left, (re)set carry 


as a side effect (high order 
A bit becomes carry) 


RRC Rotate bits right, (re)set 
carry as side effect (low 
order A bit becomes carry) 


RAL Rotate carry/A register to 
left (carry is involved in 
the rotate) 


RAR Rotate carry/A register to 
right (carry is involved in 
the rotate) 


DAD e3 DAD B Double precision add 
register pair e3 to HL (e3 
must produce B, D, H, or SP) 


Control Instructions 
The four remaining instructions are categorized as control 
instructions, and are listed below 

HLT Halt the 8080 processor 

DI Disable the interrupt system 

El Enable the interrupt system 

NOP No operation 
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Error Messages 


When errors occur within the assembly language program, they 
are listed as single character flags in the leftmost position of the 
source listing. The line in error is also echoed at the console so 
that the source listing need not be examined to determine if errors 
are present. The error codes are 


D 


Data error: element in data statement cannot be 
placed in the specified data area 


Expression error: expression is ill-formed and 
cannot be computed at assembly time 


Label error: label cannot appear in this context 
(may be duplicate label) 


Not implemented: features which will appear in 
future ASM versions (e.g., macros) are recognized, 
but flagged in this version 


Overflow: expression is too complicated (I.e., too 
many pending operators) to compute; simplify it 
Phase error: label does not have the same value 
on two subsequent passes through the program 


Register error: the value specified as a register is 
not compatible with the operation code 


Value error: operand encountered in expression is 
improperly formed 
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Several error messages are printed which are due to terminal 
error conditions 


NO SOURCE FILE The file specified in the ASM 
PRESENT command does not exist on 
disk 


NO DIRECTORY SPACE The disk directory Is full; erase 
files which are not needed, 


and retry 
SOURCE FILE NAME Improperly formed ASM file 
ERROR name (e.g., It is specified with 
“2” fields) 
SOURCE FILE READ Source file cannot be read 
ERROR properly by the assembler, 


execute a TYPE to determine 
the point of error 


OUTPUT FILE WRITE Output files cannot be written 

ERROR properly, most likely cause is 
a full disk; erase and retry 

CANNOT CLOSE FILE Output file cannot be closed, 
check to see if disk is write 
protected 


A Sample Session 


The following session shows interaction with the assembler and 
debugger in the development of a simple assembly language 
program. 


ASM SORT Assemble SORT.ASM 


CP/M ASSEMBLER - VER 1 0 

015C next free address 

O003H USE FACTOR % of table used 00 to FF (hexadecimal) 
END OF ASSEMBLY 


DIR SORT * 


BaEREHBREBREeEBEBeBREHREEBREEREHEEBEHEBREEE BE EE ES 


a fa OEE eee a ie ae 


] 


aa 8 


sSe8ece8 83 88a 


Jj 


- 
- 
- 
a 
ry 
- 
Py 
rs 


SORT 
SORT 
SORT 
SORT 


ASM 


source file 
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BAK backup from last edit 

PRN print file (contains tab characters) 
HEX machine code file 

A>TYPE SORT PRN 


machine code 
location 


0100 


0100 
0103 
0105 
0108 


a 


generated machine code 
214601+/ SORT 


3601 
214701 
3600 


7E COMP: 


FEO9 
D21901 


214601 ) 
7EB7C20001 


FF 


‘truncated 


’ 


5F16002148CONT: 


4E792346 


23 
965778239E _ 
DA3FO1 


B2CA3F01 
56702B5E 
712B722B73 


21460134 


21470134C3INCI: 


00 S 
I: 
050064001 EAV: 


= N 
“equate value 


Source line 


SORT PROGRAM IN CP/M ASSEMBLY LANGUAGE 
START AT THE BEGINNING OF THE TRANSIENT PROGRAM AR 


ORG 100H 

LX! H,SW  ; ADDRESS SWITCH TOGGLE 

MVI M, 1 ; SET TO 1 FOR FIRST ITERATION 
LXI| H, | ; ADDRESS INDEX 

MVI M, 0 ;1=0 

COMPARE | WITH ARRAY SIZE 

MOV A,M ;A REGISTER = | 

CPI N-1 » CY SET IF |< (N-1) 

JNC CONT = ;CONTINUE IF | <= (N-2) 


END OF ONE PASS THROUGH DATA 

LXI| H,SW = ; CHECK FOR ZERO SWITCHES 
MOV A,M! ORA A! JNZ SORT ; END OF SORT IF SW=O 
RST 7 ;GO TO THE DEBUGGER INSTEAD OF RE 
CONTINUE THIS PASS 

ADDRESSING I, SO LOAD AV(I) INTO REGISTERS 

MOV E,A! MVI D,O! LX! H,AV! DAD D! DAD D 

MOV C,M! MOV A,C! INX H! MOV B M 

LOW ORDER BYTE INA AND C, HIGH ORDER BYTE IN B 


MOV HAND L TO ADDRESS AV(I + 1) 
INX H 


COMPARE VALUE WITH REGS CONTAINING AV(1) 
SUB M! MOV D,A! MOV A,B! INX H!SBBM_ ;SUBTRACT 


BORROW SET IF AV(I+1) > AV(I) 
JC INCI ; SKIP IF IN PROPER ORDER 


CHECK FOR EQUAL VALUES 

ORA D! JZ INCI ; SKIP IF AV(I) = AV(I+1) 

MOV D,M! MOV M,B! DCX H! MOV E,M 

MOV M,C! DCX H! MOV M,D! DCX H! MOV M,E 


INCREMENT SWITCH COUNT 
LXI H,SW! INR M 


INCREMENT | 
LXIH,I! INR M! JMP COMP 


DATA DEFINITION SECTION 

DB 0 ; RESERVE SPACE FOR SWITCH COUNT 
DS 1 ; SPACE FOR INDEX 

DW 5,100,30,50,20,7,1000,300, 100, —32767 

($-AV)/2 ; COMPUTE N INSTEAD OF PRE 
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A>TYPE SORT.HEX 


:10010000214601360121470136007EFE09D2190140 
:100110002146017EB7C20001FF5F 1600214801 1983 
:10012000194E792346239657 78239EDA3F01B2CAA7 
:100130003F0156702B5E712B722B732146013421C7 
:07014000470134C30A01006E 

:1001480005006400 1 E00320014000700E8032C01BB 


machine code 
in HEX format 


:0401580064000180BE 
‘0000000000 
A>DDT SORT.HEX start debug run 
16K DDT VER 1.0 
NEXT PC 
815C 0000 default address (no address on END statement) 
—XP 
P=0000 100 change PC to 100 
—UFFFF untrace for 65535 steps abort with 
rubout 
COZOMOEOIO A=00 B=0000 D=0000 H=0000 S=0100 P=0100 LXI H,0146*0100 
—T10 trace 10,, steps 
COZOMOEOIO A=01 B=0000 D=0000 H=0146 S=0100 P=0100 LXI H,0146 
COZOMOEOIO A=01 B=0000 D=0000 H=0146 S=0100 P=0103 MVI M,01 
COZOMOEOIO A=01 B=0000 D=0000 H=0146 S=0100 P=0105 LX! H,0147 
COZOMOEOIO A=01 B=0000 D=0000 H=0147 S=0100 P=0108 MVI M,00 
COZOMOEOIO A=01 B=0000 D=0000 H=0147 S=0100 P=010A MOV A,M 
COZOMOEOIO A=00 B=0000 D=0000 H=0147 S=0100 P=010B CPI 09 
C1ZOM1EOI0 A=00 B=0000 D=0000 H=0147 S=0100 P=010D JNC 0119 
C1ZOM1EOIO A=00 B=0000 D=0000 H=0147 S=0100 P=0110 LXIl H,0146 
C1ZOM1EOIO A=00 B=0000 D=0000 H=0146 S=0100 P=0113 MOV A,M 
C1ZOM1EOIO A=01 B=0000 D=0000 H=0146 S=0100 P=0114 ORA A 
COZOMOEOIO A=01 B=0000 D=0000 H=0146 S=0100 P=0115 JNZ 0100 
COZOMOEOIO A=01 B=0000 D=0000 H=0146 S=0100 P=0100 LXI H,0146 
COZOMOEOIO A=01 B=0000 D=0000 H=0146 S=0100 P=0103 MVI M,01 
COZOMOEOIO A=01 B=0000 D=0000 H=0146 S=0100 P=0105 LXl H,0147 
COZOMOEOIO A=01 B=0000 D=0000 H=0147 S=0100 P=0108 MVI M,00 
COZOMOEOIO A=01 B=0000 D=0000 H=0147 S=0100 P=010A MOV A,M*010B 
—A10D — 
stopped at 
010D JC 119 change to a jump on carry 10BH 
0110 
— XP 
P=010B 100 reset program counter back to beginning of program 
—T10 trace execution for 10H steps 
COZOMOEOIO A=00 B=0000 D=0000 H=0147 S=0100 P=0100 LXI H,0146 
COZOMOEOIO A=00 B=0000 D=0000 H=0146 S=0100 P=0103 MVI M,0O1 
COZOMOEOIO A=00 B=0000 D=0000 H=0146 S=0100 P=0105 LXI H,0147 
COZOMOEOIO A=00 B=0000 D=0000 H=0147 S=0100 P=0108 MVI M,00 ; 
COZOMOEOIO A=00 B=0000 D=0000 H=0147 S=0100 P=010A MOV AM : Sad 
COZOMOEOIO A=00 B=0000 D=0000 H=0147 S=0100 P=010B CPI 09 
C1ZOM1EOIO A=00 B=0000 D=0000 H=0147 S=0100 P=010D JC 0119 
C1ZOM1E0IO A=00 B=0000 D=0000 H=0147 S=0100 P=0119 MOV EA 
C1ZOM1E0IO A=00 B=0000 D=0000 H=0147 S=0100 P=011A MVI D,OO 
C1ZOM1E0IO A=00 B=0000 D=0000 H=0147 S=0100 P=011C LX! H,0148 
C1ZOM1E0IO A=00 B=0000 D=0000 H=0148 S=0100 P=011F DAD D 
COZOM1E0IO A=00 B=0000 D=0000 H=0148 S=0100 P=0120 DAD OD 
COZOM1E0IO A=00 B=0000 D=0000 H=0148 S=0100 P=0121 MOV C,M 
COZOM1E0IO A=00 B=0005 D=0000 H=0148 S=0100 P=0122 MOV AC 
COZOM1E0OIO A=05 B=0005 D=0000 H=0148 S=0100 P=0123_ INX H 
COZOM1EOIO A=05 B=0005 D=0000 H=0149 S=0100 P=0124 MOV B,M*0125 
Automatic 
breakpoint 
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ERRBRnRnnnenenneaen 


ia 


CP/M Assembler 143 


0100 LXI H,0146 


list some code 


010B CPI 09 from 100H 
0100 JC 0119 

0110 LXI  H,0146 

0113. MOV AM 

0114. ORA A 

ay 

0118 RST  O7 es 


O11C LXI  H0148 
— abort list with rubout 


—G,118_ start program from current PC (0125H) and run in real time to 11BH 


*0127 stopped with an external interrupt 7 from front panel (program was looping indefinitely) 
—T4 


look at looping program in trade mode 


COZOMOEOIO A=388 B=0064 D=0006 H=0156 S=0100 P=0127 MOV DA 
COZOMOEOIO A=388 B=0064 D=3806 H=0156 S=0100 P=0128 MOV A,B 
COZOMOEOIO A=00 B=0064 D=3806 H=0156 S=0100 P=0129 INX H 
COZOMOEOIO A=00 B=0064 D=3806 H=0157 S=0100 P=012A SBB  M*012B 
—D148 


ag 58 888 a8 


data is sorted,but program doesn't stop 

0148 05 00 ©7 OO 14 00 1E OO .2ncseveuss 

0150 32 00 64 OO 64 OO 2C O01 E8 O38 O01 80 00 00 00 00 2 0D.D....... 
0160 00 OO OO OO OO OO OO OO OO OO OO OO OO OO OO OO .......... 
—GO0 return to CP/M 


a 


DDT SORT.HEX _ reload the memory image 
16K DDT VER 1.0 

NEXT PC 

015C 0000 

—XP 

P=0000 100 Set PC to beginning of program 
—L10D list bad opcode 

010D JNC 0119 

0110 LX| H,0146 

— abort list with rubout 


—A10D assemble new opcode 


oe ee oe oe 


010D JC 119 
0110 


—L100 /ist starting section of program 


0100 LX H,0146 
0103 MVI M,01 
0105 LXI H,0147 
0108 MVI M,00 


— abort list with rubout 

—A103 change ‘switch’ initialization to 00 
0103 MVI M,O 

0105 


—"C return to CP/M with ctl-c (GO works as well) 


sa 85 @ao 
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SAVE 1 SORT.COM save 71 page (256 bytes, from 100H to 1FFMH) on disk in case 
we have to reload later 
A DDT SORT.COM restart DDT with 
saved memory image 
16K DDT VER 1.0 
NEXT PC 
0200 0100 “COM file always starts with address 100H 
—G run the program from PC=100H 


*0118 programmed stop (RST 7) encountered 
—D148 
data properly sorted 


0146 05 00 O07 00 14 00 TE 00 ..escsn. 

O150 G2 00 64 O00 64 00 2C OF ES O03 O01 80 00 00 00 OO 2.D.D 6 ¢ sec satdenniaces 
O160 06 ©O 00 OO ©O 00 00 00 00 00 00 00 OD 00 ©O OOi ik ssid idsisc wees ditaswons 
O170 00 00 006 00 00 00 00 00 00 OC 00 00 00 00 00 00. vaca cccidivedsawiesaa wer ese: 


— GO return to CP/M 
ED SORT.ASM make changes to original program 


ctl-Z 
*N,O° ZOTT find next ’,0” 
MVI M,O -1=0 
*— up one line in text 
LX\| H,| - ADDRESS INDEX 
*— up another line 
MVI M,1 ‘SET TO 1 FOR FIRST ITERATION 
*KT_ kill line and type next line 
LX| H,| ‘ ADDRESS INDEX 
*| insert new line 
MVI M,O -ZERO SW 
*T 
LX| H,| > ADDRESS INDEX 
*NJNC * ZOT 
JNG*T 
CONT -CONTINUE IF 1 <= (N—2) 
*—2DIC* ZOLT 
JC CONT -CONTINUE IF 1 <= (N—2) 
‘Ee source from disk A 


yao_hex to disk A 
ASM SORT.AAZ~+—— skip pm file 


CP/M ASSEMBLER — VER 17.0 


015C next address to assemble 
003H USE FACTOR 
END OF ASSEMBLY 


DDT SORT.HEX test program changes 
16K DDT VER 1.0 

NEXT PC 

015C 0000 

—G100 


*0118 
=e data sorted 

0148 B5 OO O7 OO 14 OO 1E OO........ 

0150 32 00 64 00 64 00 2C O1 ES O38 01 80 00 00 OO 00.2.0. D «& bia vesuvavndes 
0160 OO OO OO OO OO OO OO OO OO OO OO OO ODO OO ODO OOD 


— abort with rubout 


BEREEREaREBSaEEESEEEEEBEEHEEEEE SE EB 


—GO_ return to CP/M — program checks OK. 


[ 
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5 
CP/M Dynamic Debugging Tool 


Introduction 


The DDT program allows dynamic interactive testing and debugging 
of programs generated in the CP/M environment. The debugger 

is initiated by typing one of the following commands at the CP/M 
Console Command level 


DDT 
DDT filename.HEX 
DDT filename.COM 


where ‘filename’ is the name of the program to be loaded and 
tested. In both cases, the DDT program is brought into main 
memory in the place of the Console Command Processor (refer 
to the CP/M Interface Guide for standard memory organization), 
and thus resides directly below the Basic Disk Operating System 
portion of CP/M. The BDOS starting address, which is located in 
the address field of the JMP instruction at location 5H, is altered 
to reflect the reduced Transient Program Area size. 


The second and third forms of the DDT command shown above 
perform the same actions as the first, except there is a subsequent 
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automatic load of the specified HEX or COM file. The action Is 
identical to the sequence of commands 


DDT 
Ifilename.HEX or Ifilename.COM 
R 


where the | and R commands set up and read the specified 
program to test. (See the explanation of the | and R commands 
below for exact details.) 


Upon initiation, DDT prints a sign-on message in the format 


DDT VER m.m 
where 
D Digital Research standard version 
M MDS version 
| IMSAI standard version 
O Omron systems 
S Digital Systems standard version 


m.m is the revision number. 


Following the sign on message, DDT prompts the operator with the 
character “-” and waits for input commands from the console. 

The operator can type any of several single characters commands, 
terminated by a carriage return to execute the command. Each 
line of input can be line-edited using the standard CP/M controls 


rubout remove the last character typed 
Control-X remove the entire line, ready for re-typing 
Control-C system reboot 


Any command can be up to 32 characters in length (an automatic 
carriage return is inserted as the 33rd character), where the first 
character determines the command type. 
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A enter assembly language mnemonics with 
operands 

D display memory in hexadecimal and ASCII 

F fill memory with constant data 

G begin execution with optional breakpoints 


| set up a Standard input file control block 
L list memory using assembler mnemonics 


M move a memory segment from source to 
destination 


read program for the subsequent testing 
substitute memory values 
trace program execution 


untraced program monitoring 


x Cc a @ DB 


examine and optionally alter the CPU state 


The command character, in some cases, is followed by zero, one, 
two, or three hexadecimal values which are separated by commas 
or single blank characters. All DDT numeric output is in hexadecimal 
form. In all cases, the commands are not executed until the 
carriage return Is typed at the end of the command. 


At any point in the debug run, the operator can stop execution of 
DDT using either a Control-C or GO (jump to location OOOOH), and 
save the current memory image using a SAVE command of the 
form 


SAVE n filename.COM 


where n is the number of pages (256 byte blocks) to be saved on 
disk. The number of blocks can be determined by taking the high 
order byte of the top load address and converting this number to 
decimal. For example, if the highest address in the Transient 
Program Area is 1234H then the number of pages is 12H, or 18 
in decimal. Thus the operator could type a Control-C during the 
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debug run, returning to the Console Processor level, followed by 
SAVE 18 X.COM 


The memory image is saved as X.COM on the diskette, and can 
be directly executed by simply typing the name X. If further testing 
is required, the memory image can be recalled by typing 


DDT X.COM 
which reloads the previously saved program from location 100H 
through page 18 (12FFH). The machine state is not a part of the 


COM file, and thus the program must be restarted from the 
beginning in order to properly test It. 


DDT Commands 


The individual commands are given below in some detail. In 

each case, the operator must wait for the prompt character (-) 
before entering the command. In the explanation of each command, 
the command letter is shown in some cases with numbers 
separated by commas, where the numbers are represented by 
lower case letters. These numbers are always assumed to be ina 
hexadecimal radix, and from one to four digits in length (longer 
numbers will be automatically truncated on the right). 


Many of the commands operate upon a “CPU state” which 
corresponds to the program under test. The CPU state holds the 
registers of the program being debugged, and initially contains 
zeroes for all registers and flags except for the program counter (P) 
and stack pointer (S), which default to 100H. The program 

counter is subsequently set to the starting address given in the last 
record of a HEX file if a file of this form is loaded (see the | and R 
commands). 
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The A (Assemble) Command 


DDT allows inline assembly language to be inserted into the current 
memory image using the A command which takes the form 


As 


where s is the hexadecimal starting address for the inline 
assembly. DDT prompts the console with the address of the next 
instruction to fill, and reads the console, looking for assembly 
language mnemonics (see the Intel 8080 Assembly Language 
Reference Card for a list of mnemonics), followed by register 
references and operands in absolute hexadecimal form. Each 
successive load address Is printed before reading the console. 
The A command terminates when the first empty line Is input from 
the console. 


Upon completion of assembly language input, the operator can 
review the memory segment using the DDT disassembler. (See the 
L command.) 


Note that the assembler/disassembler portion of DDT can be 
overlayed by the transient program being tested, in which case the 
DDT program responds with an error condition when the A and L 
commands are used. 


The D (Display) Command 


The D command allows the operator to view the contents of 
memory in hexadecimal and ASCII formats. The forms are 


D 
Ds 
Ds, f 


In the first case, memc ry is displayed from the current display 
address (Initially 100H), and continues for 16 display lines. Each 
display line takes the form shown below 


aaaa bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb cccccccccccccccc 
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where aaaa is the display address in hexadecimal, and bb represents 
data present in memory starting at aaaa. The ASCII characters 
starting at aaaa are given to the right (represented by the sequence 
of c’s), where non-graphic characters are printed as a period (.) 
symbol. Note that both upper and lower case alphabetics are 
displayed, and thus will appear as upper case symbols on a 
console device that supports only upper case. Each display line 
gives the values of 16 bytes of data, except that the first line 
displayed is truncated so that the next line begins at an address 
which is the multiple of 16. 


The second form of the D command shown above is similar to 

the first, except that the display address Is first set to address s. 
The third form causes the display to continue from address s 
through address f. In all cases, the display address is set to the first 
address not displayed in this command, so that a continuing 
display can be accomplished by issuing successive D commands 
with no explicit addresses. 


Excessively long displays can be aborted by pushing the rubout 
Key. 


The F (Fill) Command 


The F command takes the form 
Fs.ic 


where s is the starting address, f is the final address, andc isa 
hexadecimal byte constant. The effect is as follows: DDT stores the 
constant c at address s, increments the value of s and tests 

against f. If s exceeds f then the operation terminates, otherwise 
the operation is repeated. Thus, the fill command can be used to 
set a memory block to a specific constant value. 
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The G (Go) Command 


Program execution is started using the G command, with up to two 
optional breakpoint addresses. The G command takes one of the 
forms 


G 

Gs 
Gs,b 
Gs,b,c 
G,b 
(3,0.C 


The first form starts execution of the program under test at the 
current value of the program counter in the current machine 

state, with no breakpoints set. The current program counter can be 
viewed by typing an X or XP command. The second form is 

similar to the first except that the program counter in the current 
machine state is set to address s before execution begins. The 
third form is the same as the second, except that program execution 
stops when address b is encountered (b must be in the area of 

the program under test). The instruction at location b is not executed 
when the breakpoint is encountered. The fourth form is identical 

to the third, except that two breakpoints are specified, one at b and 
the other at c. Encountering either breakpoint causes execution 

to stop, and both breakpoints are subsequently cleared. The last 
two forms take the program counter from the current machine 
state, and set one and two breakpoints, respectively. 


Execution continues from the starting address in real-time to the 
next breakpoint. That is, there is no intervention between the 
starting address and the break address by DDT. Thus, if the program 
under test does not reach a breakpoint, control cannot return to 
DDT. Upon encountering a breakpoint, DDT stops execution and 
types 


*q 
where d is the stop address. The machine state can be examined 


at this point using the X (Examine) command. The operator must 
specify breakpoints which differ from the program counter address 
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at the beginning of the G command. Thus, if the current program 
counter Is 1234H, then the commands 


G,1234 
and 

G400,400 
both produce an immediate breakpoint, without executing any 
instructions whatsoever. 


The | (Input) Command 


The | command allows the operator to insert a file name into the 
default file control block at 5CH (the file control block created by 
CP/M for transient programs Is placed at this location; see the 
CP/M Interface Guide). The default FCB can be used by the 
program under test as if it had been passed by the CP/M Console 
Processor. Note that this file name is also used by DDT for 

reading additional HEX and COM files. The form of the | command is 


Ifilename 
or 
Ifilename.filetype 


If the second form is used, and the filetype is either HEX or 

COM, then subsequent R commands can be used to read the pure 
binary or hex format machine code (see the R command for 
further details). 


The L (List) Command 


The L command is used to list assembly language mnemonics In a 
particular program region. The forms are 


L 
Ls 
Lst 
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The first command lists twelve lines of disassembled machine 

code from the current list address. The second form sets the list 
address to s, and then lists twelve lines of code. The last form 

lists disassembled code from s through address f. In all three cases, 
the list address is set to the next unlisted location in preparation 
for a subsequent L command. Upon encountering an execution 
breakpoint, the list address is set to the current value of the 
program conter (see the G and T commands). Again, long typeouts 
can be aborted using the rubout key during the list process. 


The M (Move) Command 


The M command allows block movement of program or data 
areas from one location to another in memory. The form is 


Ms, f,d 
where s Is the start address of the move, f is the final address of the 
move, and d Is the destination address. Data is first moved from s 


to d, and both addresses are incremented. If s exceeds f then the 
move operation stops, otherwise the move operation Is repeated. 


The R (Read) Command 


The R command Is used in conjunction with the | command to 
read COM and HEX files from the diskette into the transient 
program area in preparation for the debut run. The forms are 


R 
Rb 


where b is an optional bias address which is added to each program 
or data address as it is loaded. The load operation must not 
overwrite any of the system parameters from OOOH through OFFH 
(i.e., the first page of memory). If b is omitted, then b = OOOO is 
assumed. The R command requires a previous | command, 
specifying the name of a HEX or COM file. The load address for 
each record is obtained from each individual HEX record, while 
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an assumed load address of 100H is taken for COM files. Note that 
any number of R commands can be issued following the | 
command to re-read the program under test, assuming the tested 
program does not destroy the default area at 5CH. Further, any 

file specified with the filetype “COM” is assumed to contain machine 
code in pure binary form (created with the LOAD or SAVE 
command), and all others are assumed to contain machine code in 
Intel hex format (produced, for example), with the ASM commana). 


Recall that the command 
DDT filename.filetype 
which initiates the DDT program is equivalent to the commands 
DDT 
-lfilename.filetype 
-R 
Whenever the R command is issued, DDT responds with either the 
error indicator “?” (file cannot be opened, or a checksum error 


occurred in a HEX file), or with a load message taking the form 


NEXT PC 
nnnn pppp 


where nnnn ts the next address following the loaded program, 


and pppp is the assumed program counter (100H for COM files, or 
taken from the last record if a HEX file is specified). 


The S (Set) Command 


The S command allows memory locations to be examined and 
optionally altered. The form of the command is 


SS 
where s Is the hexadecimal starting address for examination and 


alteration of memory. DDT responds with a numeric prompt, 
giving the memory location, along with the data currently held in 
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the memory location. If the operator types a carriage return, then 
the data is not altered. If a byte value is typed, then the value Is 
stored at the prompted address. In either case, DDT continues to 
orompt with successive addresses and values until either a period 
(.) is typed by the operator, or an invalid input value is detected. 


The T (Trace) Command 


The T command allows selective tracing of program execution 
for 1 to 65535 program steps. The forms are 


- 
Tn 


In the first case, the CPU state is displayed, and the next 
program step is executed. The program terminates immediately, 
with the termination address displayed as 


*“hhhh 


where hhhh is the next address to execute. The display address 
(used in the D commana) is set to the value of H and L, and the list 
address (used in the L command) is set to hhhh. The CPU state 

at program termination can then be examined using the X command. 


The second form of the T command is similar to the first, except 
that execution is traced for n steps (n is a hexadecimal value) 
before a program breakpoint occurs. A breakpoint can be forced in 
the trace mode by typing a rubout character. The CPU state is 
displayed before each program step is taken in trace mode. The 
format of the display is the same as described in the X command. 


Note that program tracing is discontinued at the interface to 
CP/M, and resumes after return from CP/M to the program under 
test. Thus, CP/M functions which access I/O devices, such as 

the diskette drive, run in real-time, avoiding I/O timing problems. 
Programs running in trace mode execute approximately 500 
times slower than real time since DDT gets control after each user 
instruction is executed. Interrupt processing routines can be 
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traced, but it must be noted that commands which use the breakpoint 
facility (G, T, and U) accomplish the break using a RST 7 instruction, 
which means that the tested program cannot use this interrupt 
location. Further, the trace mode always runs the tested program 
which interrupts enabled, which may cause problems if 
asynchronous interrupts are received during tracing. 


Note also that the operator should use the rubout key to get control 


back to DDT during trace, in order to ensure that the trace for the 
current instrucion is completed before interruption. 


The U (Untrace) Command 


The U command is identical to the T command except that 
intermediate program steps are not displayed. The untrace mode 
allows from 1 to 65535 (OFFFFH) steps to be executed in 
monitored mode, and is used principally to retain control of an 
executing program while it reaches steady state conditions. All 
conditions of the T command apply to the U command. 


The X (Examine) Command 


The X command allows selective display and alteration of the 
current CPU state for the program under test. The forms are 


Xx 
Xr 


where r is one of the 8080 CPU registers 


C Carry Flag (O/1) 

Z Zero Flag (0/1) 

M Minus Flag (O/1) 

E Even Parity Flag (O/1) 

| Interdigit Carry (O/1) 

A Accumulator (O-FF) 

B BC register pair (O-FFFF) 
D DE register pair (O-FFFF) 
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H HL register pair (O-FFFF) 
S Stack Pointer (O-FFFF) 
a Program Counter (O-FFFF) 


In the first case, the CPU register state is displayed in the format 
CfZfMfEflf A=bb B=dddd D=dddd H=dddd S=dddd P=dddd inst 


where f is aQ or 1 flag value, bb is a byte value, and dddd is a 
double byte quantity corresponding to the register pair. The “inst” 
field contains the disassembled instruction which occurs at the 
location addressed by the CPU state’s program counter. 


The second form allows display and optional alteration of register 
values, where r is one of the registers given above (C, Z, M, E, |, 

A, B, D, H, S, or P). In each case, the flag or register value is the 
first displayed at the console. The DDT program then accepts 

input from the console. If a carriage return is typed, then the flag or 
register value is not altered. If a value in the proper range is 

typed, then the flag or register value is altered. Note that BC, DE, 
and HL are displayed as register pairs. Thus, the operator types 

the entire register pair when B, C, or the BC pair is altered. 


Implementation Notes 


The organization of DDT allows certan non-essential portions to be 
overlayed in order to gain a larger transient program area for 
debugging large programs. The DDT program consists of two parts: 
the DDT nucleus and the assembler/disassembler module. The 
DDT nucleus is loaded over the Console Command Processor, and, 
although loaded with the DDT nucleus, the assembler/disassembler 
is overlayable unless used to assemble or disassemble. 


In particular, the BDOS address at location 6H (address field of 
the JMP instruction at location 5H) is modified by DDT to address 
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the base location of the DDT nucleus which, in turn, contains a 
JMP instruction to the BDOS. Thus, programs which use this address 
field to size memory see the logical end of memory at the base 

of the DDT nucleus rather than the base of the BDOS. 


The assembler/disassembler module resides directly below the 
DDT nucleus in the transient program area. If the A, L, T, or X 
commands are used during the debugging process then the DDT 
program again alters the address field at 6H to include this 

module, thus further reducing the logical end of memory. If a 
program loads beyond the beginning of the assembler/disassembler 
module, the A and L commands are lost (their use produces a °?” 

in response), and the trace and display (T and X) commands list the 
“inst” field of the display in hexadecimal, rather than as a decoded 
instruction. 


Sample Session 


The following example shows an edit, assemble, and debug for a 
simple program which reads a set of data values and determines 
the largest value in the set. The largest value is taken from the 
vector, and stored into “LARGE” at the termination of the program. 


ED SCAN.ASM 
| tab character i= faut echo 
T—1! ORG T-1100H L—L; START OF TRANSIENT AREA 
MVI B,LEN -* LENGTH OF VECTOR TO SCAN 
MVI C0 ; LARGER—RST VALUE SO FAR 
LOOP POOL LXI H,VECT > BASE OF VECTOR 
LOOP; 4 MOV A,M ;GET VALUE 
rubout | SUB C “LARGER VALUE IN C? 
deletes JNC NFOUND- ; JUMPIF LARGER VALUE NOT FOUND 
;characters NEW LARGEST VALUE, STORE IT TO C 
MOV C.A 
NFOUND: INX H “TO NEXT ELEMENT 
BCR B Ce AU ee pon —andeniooe 
JNZ LOOP FOR ANOTHER 


characters typed 


END OF SCAN, STORE C OY PIOGIAMINEY: 


MOV A,C GET LARGEST VALUE 
STA LARGE 
JMP 0 ; REBOOT 
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: TEST DATA 

VEC: DB 2,0,4,9,9,6,1,0 

LEN EQU $—VECT ;LENGTH 

LARGE: DS 1 ; LARGEST VALUE ON EXIT | 
END 

tZ*BOP 

ORG 100H ‘START OF TRANSIENT AREA 
MVI B,LEN *LENGTH OF VECTOR TO SCAN 
MVI Co “LARGEST VALUE SO FAR 
LXI| H VECT ‘ BASE OF VECTOR 

LOOP: MOV A,M -GET VALUE 
SUB G ‘LARGER VALUE IN C? 
JNC NFOUND~ ; JUMP IF LARGER VALUE NOT FOUND 
NEW LARGEST VALUE, STORE IT TO C 
MOV CA 

NFOUND: INX H ‘TO NEXT ELEMENT 

DCR B ‘MORE TO SCAN? 
JNZ LOOP “FOR ANOTHER 
END OF SCAN, STORE C 
MOV A,C ‘GET LARGEST VALUE 
STA LARGE 
JMP 0 * REBOOT 

; TEST DATA 

VECT: DB 204.0,5,6,15 

LEN EQU $—VECT ;LENGTH 

LARGE: DS 1 ‘LARGEST VALUE ON EXIT 
END 

a = «— End of Edit 
ASM SCAN 


Start Assembler 


CP/M ASSEMBLER — VER 1.0 

0122 

002H USE FACTOR 

END OF ASSEMBLY Assembly Complete — Look at Program Listing 


TYPE SCAN.PRN 
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Code Address Source Program 
0100 Machine Code ORG 100H ‘START OF TRANSIENT AREA 
0100 0608 MVI B,LEN * LENGTH OF VECTOR TO SCAN 
0102 OEOO MVI C0 > LARGEST VALUE SO FAR 
0104 211901 LXI| H, VECT. ;BASE OF VECTOR 
0107 7E LOOP: MOV A,M >GET VALUE 
0108 91 SUB C “LARGER VALUE IN C? 
0109 D20D01 JNC NFOUND- ; JUMP IF LARGER VALUE NOT FOUND 
NEW LARGEST VALUE, STORE IT TO C 
010C 4F MOV CA 
010D 23 NFOUND — INX H -TO NEXT ELEMENT 
O10E O05 DCR B ‘MORE TO SCAN? 
010F ©C20701 JNZ LOOP *>FOR ANOTHER 
END OF SCAN, STORE C Ld 

0112 79 MOV A,C -GET LARGEST VALUE 
0113 322101 STA LARGE 
0116 C30000 JMP ¢) > REBOOT | 

Code/data listing - Lu 

truncated . TEST DATA 

0119 0O200040305VECT: DB 2,0,4.3,5,5,1;5 LJ 
0008 = LEN EQU $—VECT ;LENGTH 
0121 value of) LARGE: DS 1 “LARGEST VALUE ON EXIT 
0122 Equate END LJ 
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A> 


DDT SCAN. HEX Start Debugger using hex format machine code 


16K DDT VER 1.0 


NEXT PC 

0121 0000 

—X \________ Jast load address + 1 next instruction 
{— to execute at 


COZOMOEOIO A=00 B=0000 D=0000 H=0000 S=0100 P=0000 OUT 7F PC=0 
=F 
is Examine registers before debug run 


P=0000 100 

= Change PC to 100 
—X took at registers again PC changed 
COZOMOEOIO A=00 B=0000 D=0000 H=0000 S=0100 P=0100 MVI Bos \ 
—L100 Next instruction 


to execute at PC=100 
0100 MVI B,08 
0102 MVI C,00 
0104 = LX | H,0119 


0107 MOV A.M Disassembled Machine 
0108 SUB GC Code at 100H 

0109 JNC 010D (See Source Listing 
010C MOV CA for comparison) 


011A NOP A little more 

011B. INR B machine code 
011C_—INX B (note that Program 
011D DCR B ends at location 116 


0120 DCR B 
0121 LXI| D,2200 
0124 ~=LXI H,0200 


—A116 enter inline assembly mode to change the JMP to 0000 into a RST 7, which 
will cause the program under test to return to DDT if 116H 
0116 RST7 is ever executed. 


0117 (single carriage return stops assembly mode) 


—L113 List Code at 113H to check that RST 7 was properly inserted 


0113, STA 01 21______—_ inplace of JMP 
0116 RST O07 

0117 NOP 

0118 NOP 

0119 STAX B 

011A NOP 


011B INR B 
O11C ~=INX B 


162 


=A 


Look at registers 
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COZOMOEOIO A=00 B=0000 D=0000 H=0000 S=0100 P=0100 MVI 
initial CPU state, before 
COZOMOEOIO A=00 B=0000 D=0000 H=0000 S=0100 P=0100 MVI 


=a 


ae! 


Execute Program for one step. 


Trace one step again (note 08H in B) 


B,08 


is executed 


B,08*0102 


automatic breakpoint 


COZOMOEOIO A=00 B=0000 D=0000 H=0000 S=0100 P=0102 
—T Trace again (Register C is cleared) 


MVI 


C,00*0104 


COZOMOEOIO A=00 B=0800 D=0000 H=0000 S=0100 P=0104 LXIH,0119*0107 
—T3 Trace three steps 


COZOMOEOIO A=00 B=0800 D=0000 H=0119 S=0100 P=0107 
COZOMOEOIO A=02 B=0800 D=0000 H=0119 S=0100 P=0108 SUB C 
A=02 B=0800 D=0000 H=0119 S=0100 P=0109 JNC 010D*010D 


COZOMOEOI 
—D119 


Display memory starting at 119H 
Program data 


MOV A,M 


Automatic breakpoint at 10DH 


O14G 700: CO 04 90S 05 0B Ciacci ckvh oe ooh ose heen cers ede segar oS Tae 

0120 05/11 00 22 21 00 02 7E EB 77 13 23 EB OB ges en o WE: 

0130 C2 27 01 C3 038 29 00 O00 O00 O00 O00 O00 OO OO OD i ed Ge Tae ex 

0140 00 00 OO OO OO OO OO OO O00 O00 O00 O00 OO OO ODO OD 

0150 00 00 00 00 OO OO OO OO 00 00 OO OO OO OO OD OO Data is displayed 

0160 00 00 00 00 00 00 OO OO 00 00 OO OO 00 OO OO OO inASCII with a "0" 

0170 00 00 00 00 OO OO OO O00 00 OO OO OO OO OO OD OOD inthe position of 

0180 00 00 00 00 00 OO OO 00 00 OO OO O00 OO OO OO OD non-graphic 

0190 00 00 00 00 00 00 OO OO OO OO OO OO OO OO OO OO characters 

01A0 00 OO OO OO OO OO OO OO OO OO OO OO OO OO OD OD 

O01B0 00 00 00 0O 00 00 00 00 00 00 00 00 00 00 00 00 siswisvscncsnsssus 

0106 00 GO 60 00 OO 00 06 GO 00 OO ©0 00 00 00 00 00 iiiisseenccraenss 

=. Current CPU state 

COZOMOEOI1 A=02 B=0800 D=0000 H=0119 S=0100 P=010D INX H 

—15 Trace 5 steps from current CPU state 

COZOMOEO!I1 A=02 B=0800 D=0000 H=0119 S=0100 P=010D INX H 

COZOMOEO!I1 A=02 B=0800 D=0000 H=011A S=0100 P=010E DCR B Automatic 

COZOMOEOI1 A=02 B=0700 D=0000 H=011A S=0100 P=010F JNZ_ 0107 Breakpoint 

COZOMOEOI1 A=02 B=0700 D=0000 H=011A S=0100 P=0107 MOV A,M 

COZOMOEO!I1 A=00 B=0000 D=0000 H=0119 S=0100 P=0108 SUB C*0109 

—US5 Trace without listing intermediate states 

COZOMOE1!11 A=00 B=0700 D=0000 H=011A S=0100 P=0109 JNC 010D*0108 

—X CPU State at end of U5 

COZOMOE1I11 A=04 B=0600 D=0000 H=011B S=0100 P=0108 SUB C 

<= Run program from current PC until completion (in real-time) 

breakpoint at 116H, caused by executing RST 7 in machine code 

*0116 

—X CPU state at end of program 

COZ1MOE1I1 A=00 B=0000 D=0000 H=0121 S=0100 P=0116 RST 07 

=P examine and change program counter 

P=0116 100 

oe 

COZ1MOE1I1 A=00 B=0000 D=0000 H=0121 S=0100 P=0100 MVI- B08 

—T10 Trace 10 (hexadecimal) steps subtext for comparison 
first data element current largest value A<C 

COZ1MOE111 =0100 P=0100 MVI- B08 

COZ1MOE111 0100 P=0102 MVI  C,00 

COZ1MOE111 S=0100 P=0104 LXl H,0119 

COZ1MOE111 S=0100 P=0107 MOV A,M 

COZ1MOE111 S=0100 P=0108 SUB C 

COZOMOEOI1 S=0100 P=0109 JNC 010D 


EHREERSE & 


EBERERERESBEEE EE 


EEREEEESE& & 
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COZOMOEOI1 A=02 B=0800 D=0000 
COZOMOEO!I1 A=02 B=0800 D=0000 
COZOMOEOI1 A=02 B=0700 D=0000 
COZOMOEOI1 A=02 B=0700 D=0000 
COZOMOEOI1 A=00 B=0700 D=0000 
COZ1MOE1I11 A=00 B=0700 D=0000 
COZ1MOE1I11_ A=00 B=0700 D=0000 
COZ1MOE1I11 A=00 B=0700 D=0000 
COZOMOE1I1 A=00 B=0600 D=0000 
COZOMOE1I1 A=00 B=0600 D=0000 
-A109 

Insert a “hot patch” into 
0109 JC 10D the machine code 

to change the 
010C JNC to JC 


—GO Stop DDT so that a version of 
the patched program can be saved 


SAVE 1 SCAN.COM 


A>DDT SCAN. COM 


16K DDT VER 1.0 
NEXT PC 
0200 0100 


—L100 List some code 


0100 + MVI B,08 


0102 MVI C,00 
0104 ~=LXI 


0108 SUB C 
0109 JC 010D 
010C MOV CA 
O10D =INX H 
O10E DCR B 
O10F JNZ 0107 
0112 MOV AC 
=AP 


P=0100 


COZOMOEOIO A=00 B=0000 D=0000 
COZOMOEOIO A=00 B=0800 D=0000 
COZOMOEOIO A=00 B=0800 D=0000 
COZOMOEOIO A=0Q B=0800 D=0000 


—T10 Trace to see how patched version operates 


H=0119 S=0100 P=010D_ INX 

H=011A S=0100 P=010E DCR 
H=011A S=0100 P=010F JNZ 
H=011A S=0100 P=0107 MOV 
H=011A S=0100 P=0108 SUB 
H=011A S=0100 P=0109 JNC 
H=011A S=0100 P=010D_ INX 

H=011B S=0100 P=010E DCR 
H=011B S=0100 P=010F JNZ 

H=011B S=0100 P=0107 MOV 


Program should have moved the 
value from A into C since A>C. 
Since this code was not executed, 
it appears that the JNC should 
have been a JC instruction 


Program resides on first page, so save 1 page. 


Restart DDT with the saved memory image to continue testing 


0107 MOV AM Sf Previous patch is present in X-COM 


Data is moved from A to C 


P=0100 MVI B.08 
P=0102 MVI C.0O 
= P=0104 LXIl 
S=0100 P=0107 


7RRBRBBRERSBEESBE BRE RHE ERE BEEBE REE EE GE 


a 


COZOMOEOIO 
COZOMOEOI1 
COZOMOEOI1 
COZOMOEOI1 
COZOMOEOI1 
COZOMOEOI1 
COZOMOEOI1 
COZOMOEOI1 
C1ZOM1E0I0 
C1ZOM1E0I0 
C1ZOM1E0I0 
C1ZOMOE111 
—X 


C1ZOMOE111 
=G.108 


n=02 


A= 
Ke 
A= 
= 
A= 
A= 
A= 
A= 


02 B=0802 
02 B=0702 
02 B=0702 
00 B=0702 
FE B=0702 
FE B=0702 
FE B=0702 
FE B=0602 


A=FE B=0602 D=0000 H=011B S=0100 


Run from current PC and breakpoint at 108H 


P=0108 
P=0109 
P=010C 
P=010D 
P=010E 
P=010F 
P=0107 
P=0108 
P=0109 
P=010D 
P=010E 
P=010F 


0107*0107 


breakpoint after 16 steps e 
P=0107 MOV AM 


| 
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*0108 

= ( next data item 
C1ZOMOE1I1 A=04 B=0602 D=0000 H=011B 
mel Single step for a few cycles 
C1ZOMOE1I1 A=04 B=0602 D=0000 H=011B 
el | 

COZOMOEOI1 A=02 B=0602 D=0000 H=011B 
—X 

COZOMOEOI1 A=02 B=0602 D=0000 H=011B 
—G Run to completion 

*0116 

=f 

COZ1MOE1I1 A=03 B=0003 D=0000 H=0121 
—$121 look at the value of “LARGE” 


O121 OS Wrong Value! 


0122 OO 
0123 22 
0124 21 
0125 O00 
0126 02 
Ot27 fE 
—L100 

0100 MVI 
0102 MVI 
0104 ~LXI 
0107. MOV 
0108 SUB 
0109 JC 
010C MOV 
010D- INX 
O10E DCR 
O10F JNZ 
0112 MOV 
—L 

0113. STA 
0116 RST 
0117. NOP 
0118 NOP 
0119 STAX 
011A NOP 
011B INR 
011C + INX 
011D DCR 
O11E MVI 
0120 DCR 
—XP 

P=0116 100 


End of the S command 


Review the code 


DDDOW Ww 


Reset the PC 


S=0100 


S=0100 


S=0100 


S=0100 


S=0100 


P=0108 


P=0108 


P=0109 


P=010C 


P=0116 


SUB C 


SUB C*0109 


JC 010D*010C 


MOV C.A 


RST 07 


BRERREEREEEBRESBEEHEBHEEREEHEEBEEBEHREEBEE EE 


EEE & 


RBEEREaBBBSSESBEBHEBHRRBERBERE RE REE SE 
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—T Single step, and watch data values 


COZ1MOE1I1 
=i 
COZ1MOE111 
a | 
COZ1MOE1I1 
we} 
COZ1MOE1I1 
we | 
COZ1MOE1I1 
al 
COZOMOEOI 
il 
COZOMOEOI1 
| 
COZOMOEOI1 
va | 
COZOMOEOI1 
== J 
COZOMOEOI1 
wae 
COZOMOEOI1 
=f 
COZOMOEO! 
ny 
C1ZOM1E0I0 
=I 
C1ZOM1E010 
—L100 
0100 MVI 
0102 MVI 
0104 LX! 
0107. MOV 
0108 SUB 
0109 JC 
010C MOV 
O10D INX 
O10E DCR 
O10F JNZ 
0112 MOV 
—A108 
0108 CMP C 
0109 
—GO 


A=03 B=0003 D=0000 H=0121 S=0100 P=0100 


A=03 B=0803 D=0000 H=0121 
count set 
a largest” set 
A=03 B=0800 D=0000 H=0121 


S=0100 P=0102 


S=0100 P=0104 


base address of data set 
A=03 B=0800 D=0000 H=0119 S=0100 P=0107 


s first data item brought to A 


A=02 B=0800 D=0000 H=0119 S=0100 P=0108 
A=02 B=0800 D=0000 H=0119 S=0100 P=0109 
A=02 B=0800 D=0000 H=0119 S=0100 P=010C 
y first data item moved to C correctly 
A=02 B=0802 D=0000 H=0119 S=0100 P=010D 
A=02 B=0802 D=0000 H=011A S=0100 P=010E 
A=02 B=0702 D=0000 H=011A S=0100 P=010F 
A=02 B=0702 D=0000 H=011A S=0100 P=0107 


second data item brought toA 
A=00 B=0702 D=0000 H=011A S=0100 P=0108 


xy Subtract destroys data value which was loaded!!! 
A=FE B=0702 D=0000 H=011A S=0100 P=0109 


A=FE B=0702 D=0000 H=011A S=0100 P=010D 


This should have been a CMP so that register A 
would not be destroyed 


hot patch at 108H changes SUB to CMP 


stop DDT for SAVE 


SAVE 1 SCAN.COM 


A>DDT SCAN. COM 


Save memory image 
Restart DDT 


16K DDT VER _ 1.0 


NEXT PC 
0200 0100 


MVI 


MVI 


LX| 


MOV 


SUB 


JC 


MOV 


INX 


DCR 


JNZ 


MOV 


SUB 


JC 


INX 


B,08*0102 


C,00*0104 


H,0119*0107 


A,M+*0108 


Cx0109 


010D*010C 


C,A*010D 


H*010E 


B*010F 


0107+*0107 


A,M*0108 


C*0109 


010D*010D 


H*O010E 
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—XP 
P=0100 
=—L116 
0116 RST 07 
0117 NOP 
0118 NOP Look at code to see if it was properly loaded 
0119 STAX B (long typeout aborted with rubout) 
011A NOP 
— (rubout) 
—G.116 Run from 100H to completion 
*0116 
—XC Look at Carry (accidental typo) 
Ci 
—X Look at CPU state 
C1Z1MOE1I11 A=06 B=0006 D=0000 H=0121 S=0100 P=0116 RST O07 
—$121 Look at “Large” — it appears to be correct. 
0121 06 
0122 O00 
O23. 22 
—GO stop DDT 
ED SCAN.ASM Re-edit the source program, and make both changes 

“NSUB ctH-Z 
*OLT 

SUB C “LARGER VALUE IN C? 
*«SSUBC ZCMPCZOLT 

CMP C - LARGER VALUE IN C? 

NC NFOUND ;JUMP IF LARGER VALUE NOT FOUND 

*SNCE ZOE ZOLT 

JC NFOUND ; JUMP IF LARGER VALUE NOT FOUND 
e 
ASM _ SCAN.AAZ Re-assemble, selecting source from disk A 


CP/M ASSEMBLER — VER_ 1.0 


0122 


002H USE FACTOR 
END OF ASSEMBLY 


DDT 


SCAN.HEX 


16K DDT VER 
NEXT PC 


0121 


0000 


—L116 


0116 
0119 
O11A 
011B 


JMP 0000 

STAX B 

NOP 

INR B 
(rubout) 


hex to disk A 


Rerun debugger to check changes 


check to ensure end is still at 116H 


print to Z(selects no print file) 


PREeaBRBBRBESBESBEEBEeBEEREERBEHEEBEHEHEEHREEREBEEBREE SE 


,5Seeseeeeecegununaeneneecnaananas 
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—G100.116 Go from beginning with breakpoint at end 


x0116 breakpoint reached 
—D121 Look at “LARGE” 
correct value computed 
0121 00 22 21 00 02 7E EB 77 13 23 EB 0B 78 BT ..°!..°.W.#..A, 


0130 C2 27 01 C3 03 29 00 00 00 00 00 00 00 00 OO OO.’...).......... 
0140 00 00 00 00 00 00 00 00 00 00 OO 00 OO OO OO OO................ 


— (rubout) aborts long typeout 


—GO stop DDT, debug session complete 


“TT REEREREEREeREeEeeenReeeeee 


4°) 
a 
iq) 
= 
® 
O 
a 
® 
Sees 
® 
rou 
® 
OC 
ee 
Rp 
QO 
O 
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sen Soares 
= 

ANNE SATAN NNN 
4 

| 


SSe88e8e5e8S eee e828888 88° 


A(append) 98 

A (Assemble) 150 
ASM 

arithmetic operators 123 
assembler directives 126 
command 23 

DB 13) 

DS 132 

DW 131 

END 127 

ENDIF 129 

FOU 127 

error messages 139 
file type 52 

IF 129 

labels 120 

logical operators 123 
numeric constants 121 
operation codes 132 
ORG 126 

overview 116 
program format 118 
reserved words 122 
sample session 140 
SET 26 

string constants 123 


B 


B (block mode transfer) 33 
BAK file type 52 


BAS file type 52 

BAT: 23 

BDOS 3 

BDOS error messages 43 

BIOS 3, 46 

BIOS call conventions 50 

BOOT 49 

Built-in commands 
DIR 12 
ERA 11 
overview 
REN 13 
SAVE 14 
TYPE 14 
USER 15 


C 


Call conventions (BIOS) 46 

CCP (Console Command 
Processor) 4, 46 

Close file 64 

COM file 52 

Compute file size 76 

CON: 22 

Console input 57 

Console output 5/7 

Context editor 94 

Control characters 16 

CP/M 

built-in commands 10 
disk parameter block 5 


10 
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CP/M (continued) 

file references 7 

file types 52 

general command structure 7 
line editing 15 

logical divisions 3 

transient commands’ 17 
Currently logged drive 10 


D 
D (delete) 33 
DB 131 


DDT (Dynamic Debugging Tool) 
A (Assemble) 150 
command list 149 
D (Display) 150 
FiRill) 151 
G(Go) 152 
| (Input) 153 
implementation 158 
LibList} %52 
M (Move) 154 
overview 149 
R(Read) 154 
S (Set) 155 
T (Trace) 156 
U(Untrace) 157 
X(Examine) 157 

Delete file 65 

DIR (directory) 12 

direct console |/O 58 

DS: 132 

DUMP 483 

DW 131 


E 


E(echo) 33 

ED 

command strings 102 
command summary 110 
control characters 109 
errors 108 

memory buffer 99 
operation 95 


ED (continued) 
overview 95 
repetitive commands’ 107 
source libraries 107 
text alteration 103 
text editing 111 
text search 103 
text transfer 95 

END 127 

ENDIF 129 

EOF: 31 

EGU i127 

Error messages 
ASM 139 
BVUOS 43 
ED 108 


F 
F (filter) 33 

FDOS. 46, 50 

file control block 53 
file reference 7 


file types 52 
G 
G (get file) 34 


Get address (allocation) 70 

Get address (disk parameters) 72 
Get console status 61 

Get 1/O Byte 59 

Get Read/Only vector 71 

Get user code 72 

General command structure 7 


H 


H (hex data transfer) 34 
Hex files 52 


/ 

I (ignore) 34 
IF 129 

INP: 31 

INT file type 52 
Intel 8080 2 


SBEREBRBBBEBEEBERBEEBEHEHREHREEBEHEEBEEHRHRESEBEEBEHEE SB E 


- 
r. 
. 
a 
:. 
:. 
a. 
a. 
. 
:. 
:. 
| 
7. 
a. 
:. 
. 
| 7 
"1 
a. 
os 
ry 
- 
7 


e 
Jump codes 133 


L 

L (translate) 34 

Line editing commands 15 
List devices 23 

List output 58 

LOAD 26 

Logical devices 22 

LPT: 23 

[St 23 


M 


Make file 67 
Memory buffer organization 97 
Memory organization (CP/M) 47 


N 
N (add line numbers) 34 
NUL: 31 


O 

O (object file transfer) 34 
Open file 63 

Operand 120 
Operation codes 132 
ORG 126 

OUT: 31 

Output Control 15 


P 

P (include page ejects) 34 
PIP 27 

Physical devices 23 
Print string 59 

PRN: 931 

PTP: 23 

PTR? 23 

PUN: 23 

Punch output 58 


Q 


Q (quit copying) 34 


R 
R (read system files) 35 
RDR: 23 


Read console buffer 60 
Read random 73 

Read sequential 66 
Reader input 57 

REL file 52 

REN (REName) 13 

Reset disk system 62 
Return current disk 69 
Return login vector 68 
Return version number 61 


S 


S (start copying) 35 

Sample programs 

file dump utility 81 
file-to-file copy program 78 
random access program 84 
SAVE 14 

Search for First 64 

Search for Next 65 

Select disk 62 

SET 128 

Set DMA address 69 

Set file attributes 71 

Set 1/O Byte 59 

Set random record 77 

Set usercode 72 

Special characters 8 

STAT 18 

SUBMIT 40 

SYM file 52 

System function summary 92 


r 


T (expand tabs) 35 

Text transfer operations 95 
Transient commands 17 
TTY: 2e 

TYPE 14 
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U 


U (all uppercase) 35 
WC 26 

GLA 23 

UP1: 23 

UP2: 23 

UR 23 

UR2: 23 

USER 15 


V 


V (verify) 35 
VAL 24 


W 


W (write over R/O) 35 
Write protect disk 70 
Write random 75 
Write sequential 66 


X 
XSUB 42 


Z 


Z (zero parity bit on input) 


Zilog Z-80 2 


35 


BEREBRBBESBEBESBEEHEEB ES SE 


BBEESEEBEE SB SB 


= 8 


i 
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